System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact a109af4a2858a2a965fe4df45a14908314c3e473:


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 31 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.1".#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 31 0a 23 64 65 66  BER 3008001.#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 30 2d 31 36 20 30 39 3a 34 39 3a 31 30 20 32  10-16 09:49:10 2
1080: 34 37 30 64 31 62 62 30 38 62 32 36 36 31 62 63  470d1bb08b2661bc
1090: 66 64 65 37 61 36 30 35 32 30 38 65 62 36 30 34  fde7a605208eb604
10a0: 34 38 33 36 64 35 63 22 0a 0a 2f 2a 0a 2a 2a 20  4836d5c"../*.** 
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 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4170: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
4b20: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
4b30: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
4b40: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b60: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
4b70: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
4b80: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b90: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4ba0: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4bb0: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4bc0: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4bd0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4bf0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4c00: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4c10: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
4c20: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
4c30: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
4c40: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4c50: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4c60: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4c70: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4c80: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  ed error code} {
4c90: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4ca0: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4cb0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  S: {extended res
4cc0: 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ult code} {exten
4cd0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ce0: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64  }.**.** In its d
4cf0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
4d00: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49  tion, SQLite API
4d10: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
4d20: 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67   one of 26 integ
4d30: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  er.** [SQLITE_OK
4d40: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4d50: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4d60: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4d70: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4d80: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4d90: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4da0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4db0: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4dc0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4dd0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4de0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4df0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e00: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e10: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e20: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e30: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e40: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4e50: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4e60: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4e70: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4e80: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4e90: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4ea0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4eb0: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4ec0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4ed0: 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62  t codes are enab
4ee0: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4ef0: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4f00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4f10: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4f20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4f30: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4f40: 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20  s()] API..**.** 
4f50: 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69  Some of the avai
4f60: 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72  lable extended r
4f70: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4f80: 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20  listed here..** 
4f90: 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74  One may expect t
4fa0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
4fb0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fc0: 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e  es will be expan
4fd0: 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20  d.** over time. 
4fe0: 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75   Software that u
4ff0: 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73  ses extended res
5000: 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64  ult codes should
5010: 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65   expect.** to se
5020: 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64  e new result cod
5030: 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
5040: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
5050: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5060: 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65  E_OK result code
5070: 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65   will never be e
5080: 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c  xtended.  It wil
5090: 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65  l always.** be e
50a0: 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a  xactly zero..*/.
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
5240: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
5280: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
52c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5300: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5320: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
5340: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5360: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
5380: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53a0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
53c0: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
53e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
5400: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5420: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5460: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
5480: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54a0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
54c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
54e0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
5500: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5520: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
5540: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5560: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5570: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
5580: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
5590: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55a0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
55b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
55c0: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
55d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
55e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
55f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5610: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5620: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5630: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
5640: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
5650: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5660: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5670: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5690: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56a0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
56b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
56c0: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
56d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
56e0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
56f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56  QLITE_IOERR_CONV
5700: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53  PATH          (S
5710: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
5720: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5730: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
5740: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
5750: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
5760: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5770: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
5780: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
5790: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
57c0: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
57d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
57e0: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
57f0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5800: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5810: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5820: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5840: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
5850: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5860: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
5870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5880: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
5890: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58a0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
58b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58c0: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48  ANTOPEN_CONVPATH
58d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58e0: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29  ANTOPEN | (4<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
5910: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5920: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
5930: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5940: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
5950: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
5960: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
5970: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5980: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
5990: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
59a0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59b0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
59c0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
59d0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
59e0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
59f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5a00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a10: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a20: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a50: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a70: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5ae0: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b20: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ba0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bc0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5bf0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c30: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c50: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5cb0: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5cc0: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5cd0: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5cf0: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5d00: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5d10: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5d20: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5d30: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5d40: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5d50: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  NG | (1<<8))../*
5d60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5d70: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5d80: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5d90: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5da0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5db0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5dc0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5dd0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5de0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5df0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5e00: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5e10: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5e20: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5e30: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5e50: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5e60: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ea0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5eb0: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5ef0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5f00: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5f10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5f20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5f30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5f40: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5f50: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5f60: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5f80: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5f90: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5fa0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fb0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5fc0: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5fd0: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5fe0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5ff0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
6000: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6010: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
6020: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6030: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
6050: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
6060: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
6070: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6080: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6090: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
60a0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
60b0: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
60c0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
60e0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
60f0: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
6100: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6110: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
6120: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
6130: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
6140: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6160: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6170: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
6180: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
61a0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
61b0: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
61c0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
61d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
61e0: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
61f0: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6200: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6210: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6220: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6230: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6240: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
6260: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
6270: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
6280: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6290: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
62a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
62b0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
62c0: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
62d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
62e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
62f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6300: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6310: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6320: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6330: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6340: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
6350: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
6360: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
6370: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6380: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6390: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63b0: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
63c0: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
63d0: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
63f0: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6400: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6410: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6420: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6430: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6440: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
6450: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6460: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
6470: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
6480: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
6490: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
64a0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
64b0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
64c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
64d0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
64e0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
64f0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6500: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6510: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6520: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6530: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6540: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6550: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6560: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6570: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6580: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6590: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
65a0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
65b0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
65c0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
65d0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
65e0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
65f0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6600: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6610: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6620: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6630: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6640: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6650: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6660: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6670: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6680: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6690: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
66a0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
66b0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
66c0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
66d0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
66e0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
66f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6700: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6710: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6720: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6730: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6740: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6750: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6760: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
6770: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
6780: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
6790: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
67a0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
67b0: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
67c0: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
67d0: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
67e0: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
67f0: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6800: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6810: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6820: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6830: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6840: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
6850: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
6860: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
6870: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
6880: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f  be unchanged..*/
6890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
68a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68c0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
68d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68e0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20  MIC512          
68f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
6900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6910: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
6920: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6930: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6950: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C2K             
6960: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6980: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
6990: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
69a0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
69b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
69c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
69d0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
69e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
69f0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
6a00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6a10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a40: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
6a50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a60: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20  OMIC64K         
6a70: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
6a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ab0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
6ac0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6ad0: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20  ENTIAL          
6ae0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64     0x00000400.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b00: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6b10: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30  HEN_OPEN  0x0000
6b20: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
6b30: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
6b40: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
6b50: 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a   0x00001000../*.
6b60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6b70: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6b80: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
6b90: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
6ba0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6bb0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
6bc0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6bd0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
6be0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
6bf0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
6c00: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
6c10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6c20: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
6c30: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6c40: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c60: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c80: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6c90: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6ca0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6cb0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6cc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6cd0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
6ce0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6cf0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6d00: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
6d10: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6d20: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6d30: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6d40: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6d50: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6d60: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6d70: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6d80: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6d90: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6da0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6db0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6dc0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6dd0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
6de0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6df0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6e00: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6e10: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6e20: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6e30: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6e40: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6e50: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6e60: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6e70: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6e80: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6e90: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6ea0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6eb0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
6ec0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6ed0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
6ee0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
6ef0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
6f00: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
6f10: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
6f20: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
6f30: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6f40: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6f50: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6f60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6f70: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6f80: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6f90: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6fa0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6fb0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
6fc0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
6fd0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
6fe0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
6ff0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7000: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7010: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7020: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7030: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7040: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
7050: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7060: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7070: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
7080: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
7090: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
70a0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
70b0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
70c0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
70d0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
70e0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
70f0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7100: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7110: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7120: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7130: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7140: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
7150: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
7160: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7170: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7180: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
7190: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
71a0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
71b0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
71c0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
71d0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
71e0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
71f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7200: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7210: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7220: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7230: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7240: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
7250: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7260: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
7270: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7280: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7290: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
72a0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
72b0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
72c0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
72d0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
72e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
72f0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7300: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7310: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7320: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7330: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7340: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
7350: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
7360: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
7370: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
7380: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
7390: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
73a0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
73b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
73c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
73d0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
73e0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
73f0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7400: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7410: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7420: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7430: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7440: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
7450: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
7460: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
7470: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7480: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
7490: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
74a0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
74b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
74c0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
74d0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
74e0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
74f0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7500: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7510: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7520: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7530: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7540: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
7550: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
7560: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
7570: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7580: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
7590: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
75a0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
75b0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
75c0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
75d0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
75e0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
75f0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7600: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7610: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7620: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7630: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7640: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
7650: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7660: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7680: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
7690: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
76a0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
76b0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
76c0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
76d0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
76e0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
76f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7700: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7710: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7720: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7730: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7740: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
7750: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
7760: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7770: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
7780: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7790: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
77a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
77b0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
77c0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
77d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
77e0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
77f0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
7800: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
7810: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
7820: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
7830: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
7840: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
7850: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
7860: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
7870: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7880: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
7890: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
78a0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
78b0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
78c0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
78d0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
78e0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
78f0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
7900: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
7910: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
7920: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
7930: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
7940: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
7950: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7960: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
7970: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7980: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
7990: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
79a0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
79b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
79c0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
79d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
79e0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
79f0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
7a00: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
7a10: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
7a20: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
7a30: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
7a40: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
7a50: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
7a60: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
7a70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
7a80: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
7a90: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
7aa0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
7ab0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
7ac0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
7ad0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
7ae0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
7af0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
7b00: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
7b10: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
7b20: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
7b30: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
7b40: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
7b50: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
7b60: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
7b70: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
7b80: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7b90: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
7ba0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
7bb0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
7bc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
7bd0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
7be0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
7bf0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
7c00: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
7c10: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
7c20: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
7c30: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7c40: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7c50: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7c60: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7c70: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7c80: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7c90: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7ca0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7cb0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7cc0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7cd0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
7ce0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
7cf0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
7d00: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
7d10: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
7d20: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
7d30: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7d40: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7d50: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7d60: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7d70: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7d80: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7d90: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7da0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7db0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7dc0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7dd0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
7de0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
7df0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
7e00: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7e10: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7e20: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7e30: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7e40: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7e50: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7e60: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7e70: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7e80: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7e90: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7ea0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7eb0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7ec0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7ed0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7ee0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7ef0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7f00: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7f10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
7f20: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7f30: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7f40: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7f50: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7f60: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7f70: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7f80: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
7f90: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
7fa0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
7fb0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
7fc0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
7fd0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
7fe0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
7ff0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8000: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8010: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8020: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8030: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8040: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8050: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8080: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8090: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
80a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80b0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
80c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80d0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
80e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80f0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8100: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8110: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8130: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8160: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8170: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8180: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8190: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
81a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
81b0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
81c0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
81d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
81e0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
81f0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8200: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8210: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8220: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8230: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8240: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8250: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8260: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8270: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8280: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8290: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
82a0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
82b0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
82c0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
82d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
82e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
82f0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8300: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8310: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8320: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8330: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8340: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8350: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8360: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8370: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8380: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8390: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
83a0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
83b0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
83c0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
83d0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
83e0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
83f0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8400: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8410: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8420: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8430: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8440: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8450: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8460: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8470: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8480: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8490: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
84a0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
84b0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
84c0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
84d0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
84e0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
84f0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8500: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8510: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8520: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8530: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8540: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8550: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8560: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8570: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8580: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8590: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
85a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
85b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
85c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
85d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85e0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
85f0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8600: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8610: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8630: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8640: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8650: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8660: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8670: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8680: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8690: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
86a0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
86b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
86c0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
86d0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
86f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8700: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8710: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8720: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8730: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8740: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8750: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8760: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8770: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8780: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8790: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
87b0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
87c0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
87d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
87e0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
87f0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8800: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8810: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8820: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8830: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8840: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8850: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8860: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8870: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8880: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8890: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
88a0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
88b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
88c0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
88d0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
88e0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
88f0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8900: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8910: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8920: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8930: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8940: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8950: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8960: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8970: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8980: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8990: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
89a0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
89b0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
89c0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
89d0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
89e0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
89f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8a00: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8a20: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8a30: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8a40: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
8a50: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8a60: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8a70: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8a80: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8a90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8aa0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ab0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8ac0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8ad0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8ae0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
8af0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8b00: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8b10: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8b20: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8b30: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8b40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8b50: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8b60: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8b70: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8b80: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8b90: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8ba0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8bb0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8bc0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8bd0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8be0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8bf0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8c00: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8c10: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8c20: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8c30: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8c40: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8c50: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8c60: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8c70: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8c80: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8c90: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c  is defined..** <
8ca0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
8cb0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8cc0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8cd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8ce0: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8cf0: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8d00: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8d10: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8d20: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8d30: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8d40: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8d50: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8d60: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8d70: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8d80: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8d90: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8da0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8db0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8dc0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8dd0: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8de0: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8df0: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8e00: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8e10: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8e20: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8e30: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8e40: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8e50: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8e60: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8e70: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8e80: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8e90: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
8ea0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
8eb0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
8ec0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
8ed0: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
8ee0: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
8ef0: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
8f00: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
8f10: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
8f20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8f30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8f40: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
8f50: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
8f60: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
8f70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
8f80: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
8f90: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
8fa0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
8fb0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
8fc0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
8fd0: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
8fe0: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
8ff0: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9000: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9010: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9020: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9030: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9040: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9050: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9060: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9070: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9080: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9090: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
90a0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
90b0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
90c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
90d0: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
90e0: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
90f0: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9100: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9110: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  e the [sqlite3_f
9120: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64  ile_control()] d
9130: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
9140: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
9150: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
9160: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9170: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9180: 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  D]].** ^(The [SQ
9190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
91a0: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
91b0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
91c0: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
91d0: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
91e0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
91f0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
9200: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
9210: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
9220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9230: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
9240: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
9250: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
9260: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9270: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
9280: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
9290: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
92a0: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
92b0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
92c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
92d0: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
92e0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
92f0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
9300: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
9310: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
9320: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
9330: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
9340: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
9350: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9360: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9370: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
9380: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9390: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
93a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
93b0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
93c0: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
93d0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
93e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
93f0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9400: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9410: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9420: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9430: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9440: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9450: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9460: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9470: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9480: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9490: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
94a0: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
94b0: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
94c0: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
94d0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
94e0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
94f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9500: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9510: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9520: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9530: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9540: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9550: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9560: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9570: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9580: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9590: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
95a0: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
95b0: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
95c0: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
95d0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
95e0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
95f0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9600: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9610: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9620: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9630: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9640: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9650: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9660: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9670: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9680: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9690: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
96a0: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
96b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
96c0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
96d0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
96e0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
96f0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
9700: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
9710: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
9720: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
9730: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
9740: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
9750: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
9760: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
9770: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
9780: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
9790: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
97a0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
97b0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
97c0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
97d0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
97e0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
97f0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
9800: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
9810: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
9820: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
9830: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9840: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9850: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9860: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9870: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
9880: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9890: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
98a0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
98b0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
98c0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
98d0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
98e0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
98f0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
9900: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
9910: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
9920: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
9930: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
9940: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
9950: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
9960: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
9970: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
9980: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
9990: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
99a0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
99b0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
99c0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
99d0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
99e0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
99f0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
9a00: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
9a10: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
9a20: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
9a30: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
9a40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9a50: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
9a60: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9a70: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
9a80: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9a90: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
9aa0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
9ab0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
9ac0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
9ad0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
9ae0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
9af0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9b00: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
9b10: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
9b20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
9b30: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
9b40: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
9b50: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
9b60: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
9b70: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
9b80: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
9b90: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
9ba0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
9bb0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
9bc0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
9bd0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
9be0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
9bf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9c00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9c10: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
9c20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9c30: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9c40: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9c50: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
9c60: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
9c70: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
9c80: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
9c90: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
9ca0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
9cb0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
9cc0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
9cd0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
9ce0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
9cf0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
9d00: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
9d10: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
9d20: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9d30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9d40: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
9d50: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
9d60: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
9d70: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
9d80: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
9d90: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
9da0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
9db0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
9dc0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
9dd0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
9de0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
9df0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
9e00: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
9e10: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
9e20: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
9e30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9e40: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
9e50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9e60: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
9e70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
9e80: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
9e90: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
9ea0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
9eb0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
9ec0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
9ed0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
9ee0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
9ef0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
9f00: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
9f10: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
9f20: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
9f30: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
9f40: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
9f50: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
9f60: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
9f70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
9f80: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
9f90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
9fa0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
9fb0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
9fc0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
9fd0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
9fe0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
9ff0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
a000: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
a010: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
a020: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
a030: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
a040: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
a050: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
a060: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
a070: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
a080: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
a090: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
a0a0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
a0b0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
a0c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a0d0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
a0e0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
a0f0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
a100: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
a110: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
a120: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
a130: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
a140: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
a150: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
a160: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
a170: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
a180: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
a190: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
a1a0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a1b0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
a1c0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
a1d0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
a1e0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
a1f0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
a200: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
a210: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
a220: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
a230: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a240: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a250: 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20  ]].** ^Whenever 
a260: 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  a [PRAGMA] state
a270: 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20  ment is parsed, 
a280: 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  an [SQLITE_FCNTL
a290: 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c  _PRAGMA] .** fil
a2a0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e  e control is sen
a2b0: 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73  t to the open [s
a2c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
a2d0: 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  ect correspondin
a2e0: 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61  g.** to the data
a2f0: 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69  base file to whi
a300: 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74  ch the pragma st
a310: 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20  atement refers. 
a320: 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ^The argument.**
a330: 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   to the [SQLITE_
a340: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a350: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e  le control is an
a360: 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69   array of.** poi
a370: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
a380: 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69   (char**) in whi
a390: 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c  ch the second el
a3a0: 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72  ement of the arr
a3b0: 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ay.** is the nam
a3c0: 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  e of the pragma 
a3d0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c  and the third el
a3e0: 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67  ement is the arg
a3f0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  ument to the.** 
a400: 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69  pragma or NULL i
a410: 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73  f the pragma has
a420: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e   no argument.  ^
a430: 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  The handler for 
a440: 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  an.** [SQLITE_FC
a450: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a460: 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74   control can opt
a470: 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65  ionally make the
a480: 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a   first element.*
a490: 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20  * of the char** 
a4a0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74  argument point t
a4b0: 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69  o a string obtai
a4c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
a4d0: 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20  3_mprintf()].** 
a4e0: 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
a4f0: 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e  t and that strin
a500: 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68  g will become th
a510: 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20  e result of the 
a520: 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65  pragma or.** the
a530: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
a540: 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69  f the pragma fai
a550: 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  ls. ^If the.** [
a560: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a570: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a580: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a590: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65  E_NOTFOUND], the
a5a0: 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52  n normal .** [PR
a5b0: 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67  AGMA] processing
a5c0: 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66   continues.  ^If
a5d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a5e0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a5f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a600: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
a610: 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20  then the parser 
a620: 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
a630: 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64  .** VFS has hand
a640: 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69  led the PRAGMA i
a650: 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61  tself and the pa
a660: 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61  rser generates a
a670: 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72   no-op.** prepar
a680: 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ed statement.  ^
a690: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
a6a0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a6b0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a6c0: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
a6d0: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
a6e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
a6f0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a700: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
a710: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
a720: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
a730: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
a740: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
a750: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
a760: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
a770: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
a780: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
a790: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a7a0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
a7b0: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
a7c0: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
a7d0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
a7e0: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
a7f0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
a800: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
a810: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
a820: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
a830: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a840: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
a850: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a860: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a870: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
a880: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
a890: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
a8a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a8b0: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
a8c0: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
a8d0: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
a8e0: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
a8f0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
a900: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
a910: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
a920: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
a930: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
a940: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
a950: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
a960: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
a970: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
a980: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
a990: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
a9a0: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
a9b0: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
a9c0: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
a9d0: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
a9e0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
a9f0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
aa00: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
aa10: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
aa20: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
aa30: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
aa40: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
aa50: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
aa60: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
aa70: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
aa80: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
aa90: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
aaa0: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
aab0: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
aac0: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
aad0: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
aae0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
aaf0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
ab00: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
ab10: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
ab20: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
ab30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
ab40: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
ab50: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
ab60: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
ab70: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
ab80: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
ab90: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
aba0: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
abb0: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
abc0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
abd0: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
abe0: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
abf0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
ac00: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
ac10: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
ac20: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
ac30: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
ac40: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
ac50: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
ac60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
ac70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
ac80: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
ac90: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
aca0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
acb0: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
acc0: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
acd0: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
ace0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
acf0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
ad00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ad10: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
ad20: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
ad30: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
ad40: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ad50: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ad60: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ad70: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ad80: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ad90: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ada0: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
adb0: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
adc0: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
add0: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ade0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
adf0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
ae00: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
ae10: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
ae20: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
ae30: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
ae40: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
ae50: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
ae60: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
ae70: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
ae80: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
ae90: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
aea0: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
aeb0: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
aec0: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
aed0: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
aee0: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
aef0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
af00: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
af10: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
af20: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
af30: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  ze]..**.** </ul>
af40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
af50: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
af60: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
af70: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
af80: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
af90: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
afa0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
afb0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
afc0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
afd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
afe0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
aff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b010: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b020: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b040: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
b050: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
b060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b070: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
b080: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
b090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b0a0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
b0b0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
b0c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b0d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
b0e0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
b0f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b100: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
b110: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
b120: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
b130: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
b140: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
b150: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
b160: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
b170: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
b180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b190: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b1a0: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
b1b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b1c0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
b1d0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
b1e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b1f0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
b200: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
b210: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b220: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
b230: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
b240: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b250: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
b260: 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  18../*.** CAPI3R
b270: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
b280: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
b290: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
b2a0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
b2b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
b2c0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
b2d0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
b2e0: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
b2f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
b300: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
b310: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
b320: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
b330: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
b340: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
b350: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
b360: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
b370: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
b380: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
b390: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
b3a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
b3b0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
b3c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
b3d0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
b3e0: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
b3f0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
b400: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
b410: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
b420: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
b430: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
b440: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b450: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
b460: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
b470: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
b480: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
b490: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
b4a0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b4b0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
b4c0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
b4d0: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
b4e0: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
b4f0: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
b500: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
b510: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
b520: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
b530: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
b540: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
b550: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
b560: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
b570: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
b580: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
b590: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
b5a0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
b5b0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
b5c0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
b5d0: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
b5e0: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
b5f0: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
b600: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
b610: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
b620: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
b630: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
b640: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
b650: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
b660: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
b670: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
b680: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
b690: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
b6a0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
b6b0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
b6c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
b6d0: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
b6e0: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
b6f0: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
b700: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
b710: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
b720: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
b730: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
b740: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
b750: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
b760: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
b770: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
b780: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
b790: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
b7a0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
b7b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
b7c0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
b7d0: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
b7e0: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
b7f0: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
b800: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
b810: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
b820: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
b830: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
b840: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
b850: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
b860: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
b870: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
b880: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
b890: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
b8a0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
b8b0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
b8c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
b8d0: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
b8e0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
b8f0: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
b900: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
b910: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
b920: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
b930: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
b940: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
b950: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
b960: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
b970: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
b980: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
b990: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
b9a0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
b9b0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
b9c0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
b9d0: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
b9e0: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
b9f0: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
ba00: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
ba10: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
ba20: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
ba30: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
ba40: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
ba50: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
ba60: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
ba70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
ba80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
ba90: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
baa0: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
bab0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
bac0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
bad0: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
bae0: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
baf0: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
bb00: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
bb10: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
bb20: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
bb30: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
bb40: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
bb50: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
bb60: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
bb70: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
bb80: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
bb90: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
bba0: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
bbb0: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
bbc0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
bbd0: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
bbe0: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
bbf0: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
bc00: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
bc10: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
bc20: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
bc30: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
bc40: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
bc50: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
bc60: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
bc70: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
bc80: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
bc90: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
bca0: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
bcb0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
bcc0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
bcd0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
bce0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
bcf0: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
bd00: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
bd10: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
bd20: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
bd30: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
bd40: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
bd50: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
bd60: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
bd70: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
bd80: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
bd90: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
bda0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
bdb0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
bdc0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
bdd0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
bde0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
bdf0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
be00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
be10: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
be20: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
be30: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
be40: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
be50: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
be60: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
be70: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
be80: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
be90: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
bea0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
beb0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
bec0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
bed0: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
bee0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bef0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
bf00: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
bf10: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
bf20: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
bf30: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
bf40: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
bf50: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
bf60: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
bf70: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
bf80: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
bf90: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
bfa0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
bfb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
bfc0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
bfd0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
bfe0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
bff0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
c000: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
c010: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
c020: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
c030: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c040: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
c050: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c060: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
c070: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c080: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
c090: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c0a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
c0b0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
c0c0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
c0d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
c0e0: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
c0f0: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
c100: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
c110: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
c120: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
c130: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
c140: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
c150: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
c160: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
c170: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
c180: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
c190: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
c1a0: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
c1b0: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
c1c0: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
c1d0: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
c1e0: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
c1f0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
c200: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
c210: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
c220: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
c230: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
c240: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
c250: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
c260: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
c270: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
c280: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
c290: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
c2a0: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
c2b0: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
c2c0: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
c2d0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
c2e0: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
c2f0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
c300: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
c310: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
c320: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
c340: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
c350: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
c360: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
c370: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
c380: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c390: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
c3a0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
c3b0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
c3c0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
c3d0: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
c3e0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c3f0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
c400: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
c410: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
c420: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
c430: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
c440: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
c450: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
c460: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
c470: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
c480: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
c490: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
c4a0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
c4b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
c4c0: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
c4d0: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
c4e0: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
c4f0: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
c500: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
c510: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
c520: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
c530: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
c540: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
c550: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
c560: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c570: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
c580: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
c590: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
c5a0: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
c5b0: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
c5c0: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
c5d0: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
c5e0: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
c5f0: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
c600: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
c610: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
c620: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
c630: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
c640: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
c650: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
c660: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
c670: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
c680: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
c690: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
c6a0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
c6b0: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
c6c0: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
c6d0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
c6e0: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
c6f0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
c700: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
c710: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
c720: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
c730: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
c740: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
c750: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
c760: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
c770: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
c780: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
c790: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
c7a0: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
c7b0: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
c7c0: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
c7d0: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
c7e0: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
c7f0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
c800: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
c810: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
c820: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
c830: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
c840: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
c850: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
c860: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
c870: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
c880: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
c890: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c8a0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
c8b0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c8c0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
c8d0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
c8e0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
c8f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c900: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
c910: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
c920: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
c930: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
c940: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c950: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
c960: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
c970: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
c980: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
c990: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
c9a0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
c9b0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
c9c0: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
c9d0: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
c9e0: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
c9f0: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
ca00: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
ca10: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
ca20: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
ca30: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
ca40: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
ca50: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
ca60: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
ca70: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
ca80: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
ca90: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
caa0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
cab0: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
cac0: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
cad0: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
cae0: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
caf0: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
cb00: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
cb10: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
cb20: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
cb30: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
cb40: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
cb50: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
cb60: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
cb70: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
cb80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
cb90: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
cba0: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
cbb0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
cbc0: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
cbd0: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
cbe0: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
cbf0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
cc00: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
cc10: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
cc20: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
cc30: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
cc40: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
cc50: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
cc60: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
cc70: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
cc80: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
cc90: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
cca0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
ccb0: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
ccc0: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
ccd0: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
cce0: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
ccf0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
cd00: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
cd10: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
cd20: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
cd30: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
cd40: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
cd50: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
cd60: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
cd70: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
cd80: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
cd90: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
cda0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
cdb0: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
cdc0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
cdd0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
cde0: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
cdf0: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
ce00: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
ce10: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
ce20: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
ce30: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
ce40: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
ce50: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
ce60: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
ce70: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
ce80: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
ce90: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
cea0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
ceb0: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
cec0: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
ced0: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
cee0: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
cef0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
cf00: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
cf10: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
cf20: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
cf30: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
cf40: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
cf50: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
cf60: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
cf70: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
cf80: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
cf90: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
cfa0: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
cfb0: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
cfc0: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
cfd0: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
cfe0: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
cff0: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
d000: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
d010: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
d020: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
d030: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
d040: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
d050: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
d060: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
d070: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
d080: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
d090: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
d0a0: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
d0b0: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
d0c0: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
d0d0: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
d0e0: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
d0f0: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
d100: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
d110: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
d120: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
d130: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
d140: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
d150: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
d160: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
d170: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
d180: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
d190: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
d1a0: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
d1b0: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
d1c0: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
d1d0: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
d1e0: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
d1f0: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
d200: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
d210: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
d220: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
d230: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
d240: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
d250: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
d260: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
d270: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
d280: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
d290: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d2a0: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
d2b0: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
d2c0: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
d2d0: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
d2e0: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
d2f0: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
d300: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
d310: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
d320: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
d330: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
d340: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
d350: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
d360: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
d370: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
d380: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
d390: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
d3a0: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
d3b0: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
d3c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
d3d0: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
d3e0: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
d3f0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
d400: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
d410: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
d420: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d430: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
d440: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
d450: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
d460: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
d470: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
d480: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
d490: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d4a0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
d4b0: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
d4c0: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
d4d0: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
d4e0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
d4f0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
d500: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d510: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
d520: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
d530: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
d540: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d550: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
d560: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
d570: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
d580: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
d590: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d5a0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
d5b0: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
d5c0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
d5d0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
d5e0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
d5f0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
d600: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
d610: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
d620: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
d630: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
d640: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
d650: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
d660: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
d670: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
d680: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
d690: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
d6a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
d6b0: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
d6c0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
d6d0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d6e0: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
d6f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d700: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
d710: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
d720: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
d730: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
d740: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
d750: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
d760: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
d770: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
d780: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
d790: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
d7a0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d7b0: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
d7c0: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
d7d0: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
d7e0: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
d7f0: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
d800: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
d810: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
d820: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
d830: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
d840: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d850: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d860: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
d870: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d880: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
d890: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
d8a0: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
d8b0: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
d8c0: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
d8d0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d8e0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d8f0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
d900: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
d910: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
d920: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
d930: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d940: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d950: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
d960: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
d970: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
d980: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d990: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
d9a0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d9b0: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d9c0: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
d9d0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
d9e0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
d9f0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
da00: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
da10: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
da20: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
da30: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
da40: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
da50: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
da60: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
da70: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
da80: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
da90: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
daa0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
dab0: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
dac0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
dad0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
dae0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
daf0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
db00: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
db10: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
db20: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
db30: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
db40: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
db50: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
db60: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
db70: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
db80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
db90: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
dba0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
dbb0: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
dbc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dbd0: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
dbe0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
dbf0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
dc00: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
dc10: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
dc20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
dc30: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
dc40: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
dc50: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
dc60: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
dc70: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
dc80: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
dc90: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dca0: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
dcb0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
dcc0: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
dcd0: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
dce0: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
dcf0: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
dd00: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
dd10: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
dd20: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
dd30: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
dd40: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
dd50: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
dd60: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
dd70: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
dd80: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
dd90: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
dda0: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
ddb0: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
ddc0: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
ddd0: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
dde0: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
ddf0: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
de00: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
de10: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
de20: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
de30: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
de40: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
de50: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
de60: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
de70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
de80: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
de90: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
dea0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
deb0: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
dec0: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
ded0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
dee0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
def0: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
df00: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
df10: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
df20: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
df30: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
df40: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
df50: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
df60: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
df70: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
df80: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
df90: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
dfa0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
dfb0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
dfc0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
dfd0: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
dfe0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
dff0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e000: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
e010: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
e020: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
e030: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
e040: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
e050: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e060: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
e070: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
e080: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
e090: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
e0a0: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
e0b0: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
e0c0: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
e0d0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
e0e0: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
e0f0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
e100: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
e110: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
e120: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
e130: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
e140: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
e150: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
e160: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
e170: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
e180: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
e190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e1a0: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
e1b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
e1c0: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
e1d0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
e1e0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
e1f0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
e200: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
e210: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
e220: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
e230: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
e240: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
e250: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
e260: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
e270: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
e280: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
e290: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
e2a0: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
e2b0: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
e2c0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
e2d0: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
e2e0: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
e2f0: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
e300: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
e310: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
e320: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
e330: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
e340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e350: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
e360: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e370: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e380: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e390: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
e3a0: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
e3b0: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
e3c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e3d0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
e3e0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
e3f0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
e400: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
e410: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e420: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
e430: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
e440: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
e450: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
e460: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
e470: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
e480: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
e490: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
e4a0: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
e4b0: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
e4c0: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
e4d0: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
e4e0: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
e4f0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
e500: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e510: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
e520: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
e530: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
e540: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e550: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e560: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
e570: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
e580: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
e590: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
e5a0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
e5b0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
e5c0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
e5d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
e5e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e5f0: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
e600: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
e610: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e620: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
e630: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
e640: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
e650: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
e660: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
e670: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e680: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
e690: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
e6a0: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
e6b0: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
e6c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e6d0: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
e6e0: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
e6f0: 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
e700: 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
e710: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e720: 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
e730: 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
e740: 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
e750: 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
e760: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
e770: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
e780: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
e790: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
e7a0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
e7b0: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
e7c0: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
e7d0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
e7e0: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
e7f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
e800: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
e810: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
e820: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
e830: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
e840: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e850: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
e860: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
e870: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
e880: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
e890: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
e8a0: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
e8b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e8c0: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
e8d0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
e8e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e8f0: 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
e900: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
e910: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
e920: 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
e930: 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
e940: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
e950: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
e960: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
e970: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
e980: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e990: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
e9a0: 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
e9b0: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
e9c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
e9d0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
e9e0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
e9f0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
ea00: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
ea10: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
ea20: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
ea30: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
ea40: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
ea50: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
ea60: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
ea70: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ea80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
ea90: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
eaa0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
eab0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
eac0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
ead0: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
eae0: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
eaf0: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
eb00: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
eb10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
eb20: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
eb30: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
eb40: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
eb50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eb60: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
eb70: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
eb80: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
eb90: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
eba0: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
ebb0: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
ebc0: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
ebd0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
ebe0: 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
ebf0: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
ec00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
ec10: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
ec20: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
ec30: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ec40: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
ec50: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
ec60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ec70: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
ec80: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
ec90: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
eca0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ecb0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
ecc0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
ecd0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
ece0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
ecf0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
ed00: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
ed10: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
ed20: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
ed30: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
ed40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
ed50: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
ed60: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ed70: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ed80: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
ed90: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
eda0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
edb0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
edc0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
edd0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
ede0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
edf0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
ee00: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
ee10: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
ee20: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
ee30: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
ee40: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
ee50: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
ee60: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
ee70: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
ee80: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
ee90: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
eea0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
eeb0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
eec0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
eed0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
eee0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
eef0: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
ef00: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ef10: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
ef20: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
ef30: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
ef40: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
ef50: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
ef60: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
ef70: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
ef80: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
ef90: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
efa0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
efb0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
efc0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
efd0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
efe0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
eff0: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
f000: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
f010: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
f020: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
f030: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
f040: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f050: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
f060: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
f070: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
f080: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
f090: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f0a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0b0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
f0c0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
f0d0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
f0e0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
f0f0: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
f100: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
f110: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
f120: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
f130: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
f140: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f150: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
f160: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
f170: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
f180: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
f190: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
f1a0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
f1b0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
f1c0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
f1d0: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
f1e0: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
f1f0: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
f200: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
f210: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
f220: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
f230: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
f240: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
f250: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
f260: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
f270: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
f280: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
f290: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
f2a0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f2b0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
f2c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
f2d0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
f2e0: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
f2f0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
f300: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
f310: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
f320: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f330: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
f340: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
f350: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
f360: 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
f370: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69   int sqlite3_ini
f380: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53  tialize(void);.S
f390: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
f3a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
f3b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
f3c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
f3d0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
f3e0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
f3f0: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
f400: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f410: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
f420: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f430: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f440: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
f450: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
f460: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
f470: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
f480: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
f490: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
f4a0: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
f4b0: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
f4c0: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
f4d0: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
f4e0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f4f0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
f500: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
f510: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
f520: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
f530: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
f540: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
f550: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
f560: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
f570: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
f580: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
f590: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
f5a0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
f5b0: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
f5c0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
f5d0: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
f5e0: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
f5f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f600: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
f610: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
f620: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
f630: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
f640: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
f650: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
f660: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
f670: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
f680: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
f690: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
f6a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
f6b0: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
f6c0: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
f6d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f6e0: 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
f6f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f700: 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
f710: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f720: 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
f730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
f740: 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
f750: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
f760: 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
f770: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
f780: 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
f790: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
f7a0: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
f7b0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
f7c0: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
f7d0: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
f7e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
f7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
f800: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
f810: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f820: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
f830: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
f840: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
f850: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
f860: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
f870: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
f880: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
f890: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
f8a0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
f8b0: 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
f8c0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
f8d0: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
f8e0: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
f8f0: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
f900: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
f910: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
f920: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
f930: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
f940: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
f950: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
f960: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
f970: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
f980: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
f990: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
f9a0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
f9b0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
f9c0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
f9d0: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
f9e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f9f0: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
fa00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
fa10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
fa20: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
fa30: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fa40: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
fa50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fa60: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
fa70: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
fa80: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
fa90: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
faa0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
fab0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
fac0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
fad0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
fae0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
faf0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
fb00: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fb10: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
fb20: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
fb30: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fb40: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
fb50: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
fb60: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
fb70: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
fb80: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
fb90: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
fba0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
fbb0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
fbc0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fbd0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
fbe0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
fbf0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
fc00: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
fc10: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
fc20: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
fc30: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
fc40: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
fc50: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
fc60: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
fc70: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
fc80: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
fc90: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
fca0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
fcb0: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
fcc0: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
fcd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fce0: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
fcf0: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
fd00: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
fd10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
fd20: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
fd30: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
fd40: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
fd50: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
fd60: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
fd70: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
fd80: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
fd90: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
fda0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
fdb0: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
fdc0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
fdd0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
fde0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
fdf0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
fe00: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
fe10: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
fe20: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
fe30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fe40: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
fe50: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
fe60: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
fe70: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
fe80: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
fe90: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
fea0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
feb0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
fec0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
fed0: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
fee0: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
fef0: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
ff00: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
ff10: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
ff20: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
ff30: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
ff40: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
ff50: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
ff60: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
ff70: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
ff80: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
ff90: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
ffa0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
ffb0: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
ffc0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
ffd0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
ffe0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
fff0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
10000 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
10010 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
10020 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
10030 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
10040 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
10050 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10060 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10070 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
10080 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
10090 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
100a0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
100b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
100c0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
100d0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
100e0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
100f0 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
10100 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
10110 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
10120 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
10130 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
10140 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
10150 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
10160 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
10170 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
10180 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
10190 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
101a0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
101b0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
101c0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
101d0 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
101e0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
101f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
10200 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
10210 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10220 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
10230 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
10240 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
10250 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
10260 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
10270 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
10280 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10290 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
102a0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
102b0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
102c0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
102d0 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
102e0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
102f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
10300 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
10310 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
10320 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
10330 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
10340 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
10350 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
10360 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
10370 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
10380 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10390 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
103a0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
103b0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
103c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
103d0 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
103e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
103f0 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
10400 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
10410 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
10420 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
10430 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
10440 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
10450 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
10460 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10470 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
10480 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
10490 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
104a0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
104b0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
104c0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
104d0 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
104e0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
104f0 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
10500 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
10510 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
10520 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10530 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10540 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10550 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
10560 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
10570 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
10580 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
10590 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
105a0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
105b0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
105c0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
105d0 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
105e0 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
105f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10600 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
10610 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
10620 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
10630 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
10640 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
10650 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
10660 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
10670 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
10680 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
10690 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
106a0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
106b0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
106c0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
106d0 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
106e0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
106f0 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
10700 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
10710 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
10720 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
10730 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
10740 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
10750 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
10760 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
10770 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
10780 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
10790 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
107a0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
107b0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
107c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
107d0 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
107e0 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
107f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10800 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
10810 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
10820 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
10830 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
10840 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
10850 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
10860 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
10870 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
10880 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
10890 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
108a0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
108b0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
108c0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
108d0 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
108e0 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
108f0 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
10900 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
10910 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10920 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
10930 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
10940 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
10950 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
10960 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
10970 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
10980 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
10990 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
109a0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
109b0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
109c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
109d0 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
109e0 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
109f0 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
10a00 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
10a10 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
10a20 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
10a30 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
10a40 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
10a50 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
10a60 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
10a70 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
10a80 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
10a90 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
10aa0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
10ab0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
10ac0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
10ad0 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
10ae0 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
10af0 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
10b00 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
10b10 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
10b20 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
10b30 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
10b40 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
10b50 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
10b60 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
10b70 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
10b80 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
10b90 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
10ba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10bb0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
10bc0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
10bd0 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
10be0 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
10bf0 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
10c00 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
10c10 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
10c20 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
10c30 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
10c40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
10c50 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
10c60 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
10c70 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
10c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c90 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10ca0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10cb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10cc0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
10cd0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10ce0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
10cf0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10d00 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
10d10 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
10d20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
10d30 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
10d40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10d50 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
10d60 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
10d70 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
10d80 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
10d90 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
10da0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
10db0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10dc0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10dd0 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
10de0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
10df0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
10e00 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
10e10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
10e20 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
10e30 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
10e40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10e50 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
10e60 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
10e70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10e80 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
10e90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10ea0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
10eb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
10ec0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
10ed0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
10ee0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
10ef0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
10f00 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
10f10 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
10f20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
10f30 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
10f40 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
10f50 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
10f60 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
10f70 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
10f80 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
10f90 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
10fa0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10fb0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
10fc0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10fd0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10fe0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10ff0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11000 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11010 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
11020 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
11030 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
11040 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
11050 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
11060 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
11070 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11080 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
11090 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
110a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
110b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
110c0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
110d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
110e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
110f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11100 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
11110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11120 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
11130 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11140 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11150 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11160 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11170 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11180 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
11190 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
111a0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
111b0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
111c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
111d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
111e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
111f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
11200 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
11210 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
11220 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
11230 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
11240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11250 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11260 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
11270 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
11280 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
11290 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
112a0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
112b0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
112c0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
112d0 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
112e0 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
112f0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
11300 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
11310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11320 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11330 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
11340 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11350 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11360 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11370 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11380 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11390 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
113a0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
113b0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
113c0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
113d0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
113e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
113f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
11400 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11410 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
11420 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
11430 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
11440 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11450 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11470 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
11480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11490 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
114a0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
114b0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
114c0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
114d0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
114e0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
114f0 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
11500 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
11510 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
11520 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
11530 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
11540 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
11550 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
11560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11570 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11580 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11590 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
115a0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
115b0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
115c0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
115d0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
115e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
115f0 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
11600 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
11610 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
11620 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
11630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
11640 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11650 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
11660 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
11670 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
11680 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
11690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
116a0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
116b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
116c0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
116d0 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
116e0 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
116f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11700 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11710 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11720 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11730 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11740 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11750 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11760 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
11770 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
11780 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11790 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
117a0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
117b0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
117c0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
117d0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
117e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
117f0 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
11800 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11810 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11820 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
11830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11840 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
11850 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11860 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
11870 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
11880 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
11890 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
118a0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
118b0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
118c0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
118d0 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
118e0 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
118f0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11900 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11910 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
11920 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
11930 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11940 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
11950 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11960 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
11970 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
11980 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
11990 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
119a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
119b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
119c0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
119d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
119e0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
119f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11a00 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
11a10 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
11a20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
11a30 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11a40 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11a50 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11a60 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11a70 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11a80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11a90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
11aa0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11ab0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11ac0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
11ad0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
11ae0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
11af0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b10 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
11b20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
11b30 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
11b40 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
11b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11b60 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
11b70 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
11b80 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
11b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11ba0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
11bb0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
11bc0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
11bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11bf0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
11c00 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
11c10 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
11c20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
11c30 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
11c40 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
11c50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
11c60 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
11c70 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
11c80 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
11c90 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
11ca0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
11cb0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
11cc0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
11cd0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
11ce0 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
11cf0 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
11d00 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11d10 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
11d20 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
11d30 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
11d40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
11d50 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
11d60 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
11d70 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
11d80 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11d90 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
11da0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
11db0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
11dc0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
11dd0 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
11de0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
11df0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
11e00 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
11e10 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
11e20 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
11e30 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
11e40 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
11e50 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
11e60 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11e70 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
11e80 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
11e90 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
11ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
11eb0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
11ec0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
11ed0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11ee0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
11ef0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11f00 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11f10 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
11f20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
11f30 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
11f40 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
11f50 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
11f60 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
11f70 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
11f80 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
11f90 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
11fa0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
11fb0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
11fc0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
11fd0 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
11fe0 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
11ff0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
12000 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12010 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
12020 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
12030 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
12040 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
12050 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
12060 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
12070 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
12080 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
12090 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
120a0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
120b0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
120c0 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
120d0 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
120e0 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
120f0 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
12100 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
12110 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
12120 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
12130 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
12140 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
12150 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
12160 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
12170 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
12180 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
12190 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
121a0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
121b0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
121c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
121d0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
121e0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
121f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12200 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
12210 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12220 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
12230 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
12240 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
12250 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12260 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
12270 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12280 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
12290 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
122a0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
122b0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
122c0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
122d0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
122e0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
122f0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
12300 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
12310 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12320 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
12340 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
12350 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
12360 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
12370 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
12380 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
12390 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
123a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
123b0 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  2 option..** The
123c0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
123d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
123e0 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
123f0 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
12400 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
12410 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
12420 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
12430 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
12440 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
12450 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
12460 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
12470 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
12480 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
12490 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
124a0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
124b0 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
124c0 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
124d0 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
124e0 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
124f0 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
12500 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
12510 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
12520 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
12530 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
12540 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
12550 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
12560 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
12570 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
12580 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
12590 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
125a0 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
125b0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
125c0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
125d0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
125e0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
125f0 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
12600 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
12610 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12620 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
12630 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
12640 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
12650 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
12660 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
12670 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
12680 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
12690 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
126a0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
126b0 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
126c0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
126d0 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
126e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
126f0 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
12700 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
12710 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
12720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12730 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
12740 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
12750 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
12760 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12770 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
12780 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
12790 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
127a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
127b0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
127c0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
127d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
127e0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
127f0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12800 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
12810 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
12820 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
12830 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
12840 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
12850 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
12860 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
12870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12880 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
12890 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
128a0 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
128b0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
128c0 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
128d0 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
128e0 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
128f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
12900 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
12910 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
12920 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
12930 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
12940 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
12950 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
12960 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
12970 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
12980 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
12990 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
129a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
129b0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
129c0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
129d0 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
129e0 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
129f0 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
12a00 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
12a10 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
12a20 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
12a30 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
12a40 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
12a50 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
12a60 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
12a70 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
12a80 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
12a90 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
12aa0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
12ab0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
12ac0 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
12ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12ae0 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
12af0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
12b00 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
12b10 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
12b20 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
12b30 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
12b40 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12b50 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
12b60 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
12b70 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
12b80 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
12b90 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
12ba0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
12bb0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
12bc0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
12bd0 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
12be0 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
12bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12c00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12c10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12c20 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
12c30 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12c40 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12c50 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12c60 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12c70 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12c80 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12c90 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12ca0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
12cb0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
12cc0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
12cd0 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
12ce0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
12cf0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12d00 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
12d10 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12d20 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
12d30 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
12d40 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
12d50 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12d60 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
12d70 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
12d80 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
12d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12da0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
12db0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12dc0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12dd0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12de0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12df0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12e00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12e10 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12e20 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12e30 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12e40 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12e50 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12e60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12e70 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12e80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e90 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
12ea0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
12eb0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
12ec0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
12ed0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12ee0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
12ef0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12f00 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
12f10 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12f20 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12f30 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12f40 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12f50 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
12f60 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
12f70 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12f80 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
12f90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
12fa0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
12fb0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
12fc0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
12fd0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
12fe0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
12ff0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13000 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13010 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
13020 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
13030 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
13040 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
13050 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
13060 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
13070 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
13080 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
13090 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
130a0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
130b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
130c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
130d0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
130e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
130f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13100 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13110 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13120 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13130 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13140 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13150 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13160 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13170 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
13180 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
13190 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
131a0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
131b0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
131c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
131d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
131e0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
131f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
13200 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
13210 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
13220 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13230 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
13240 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
13250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13260 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
13270 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
13280 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
13290 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
132a0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
132b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
132c0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
132d0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
132e0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
132f0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
13300 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
13310 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
13320 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13330 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
13340 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
13350 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
13360 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
13370 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
13380 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
13390 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
133a0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
133b0 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
133c0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
133d0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
133e0 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
133f0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
13400 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
13410 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13420 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
13430 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13440 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
13450 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13460 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13470 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13480 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
13490 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
134a0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
134b0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
134c0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
134d0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
134e0 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
134f0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
13500 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
13510 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13520 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
13530 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
13540 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13550 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
13560 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13580 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13590 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
135a0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
135b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
135c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
135d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
135e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
135f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
13600 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13610 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
13620 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
13630 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
13640 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13650 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
13660 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13670 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13680 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
13690 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
136a0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
136b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
136c0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
136d0 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
136e0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
136f0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
13700 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
13710 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
13720 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
13730 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
13740 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
13750 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
13760 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
13770 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
13780 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
13790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
137a0 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
137b0 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
137c0 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
137d0 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
137e0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
137f0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
13800 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
13810 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
13820 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
13830 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
13840 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
13850 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
13860 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
13870 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
13880 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13890 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
138a0 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
138b0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
138c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
138d0 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
138e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
138f0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
13900 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
13910 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
13920 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
13930 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13940 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
13950 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
13960 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
13970 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
13980 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
13990 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
139a0 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
139b0 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
139c0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
139d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
139e0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
139f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
13a00 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
13a10 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
13a20 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
13a30 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
13a40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
13a50 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
13a60 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
13a70 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
13a80 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
13a90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
13aa0 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
13ab0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
13ac0 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
13ad0 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
13ae0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
13af0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
13b00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13b10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
13b20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
13b30 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
13b40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13b50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
13b60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13b70 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
13b80 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13b90 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13ba0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
13bb0 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  . If non-zero, t
13bc0 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c  hen.** URI handl
13bd0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
13be0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
13bf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
13c00 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
13c10 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61  ling.** is globa
13c20 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
13c30 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
13c40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
13c50 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
13c60 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
13c70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
13c80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13c90 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
13ca0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
13cb0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
13cc0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
13cd0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
13ce0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
13cf0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
13d00 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
13d10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
13d20 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
13d30 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
13d40 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
13d50 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
13d60 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
13d70 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
13d80 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
13d90 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
13da0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
13db0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
13dc0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
13dd0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
13de0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
13df0 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
13e00 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
13e10 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
13e20 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
13e30 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
13e40 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
13e50 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
13e60 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
13e70 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
13e80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
13e90 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
13ea0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
13eb0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13ec0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
13ed0 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
13ee0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13ef0 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
13f00 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13f10 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
13f20 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69  s.** a boolean i
13f30 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
13f40 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
13f50 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
13f60 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20   indices for.** 
13f70 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13f80 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
13f90 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 64  timizer.  ^The d
13fa0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
13fb0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
13fc0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
13fd0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
13fe0 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
13ff0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
14000 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
14010 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
14020 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
14030 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
14040 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
14050 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
14060 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
14070 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
14080 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
14090 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
140a0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
140b0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
140c0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68  alfunction.** wh
140d0 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74  en the optimizat
140e0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  ion is enabled. 
140f0 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61   Providing the a
14100 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73  bility to.** dis
14110 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a  able the optimiz
14120 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65  ation allows the
14130 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70   older, buggy ap
14140 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74  plication code t
14150 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75  o work.** withou
14160 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69  t change even wi
14170 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  th newer version
14180 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
14190 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
141a0 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
141b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
141c0 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
141d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
141e0 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
141f0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
14200 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
14210 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
14220 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
14230 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
14240 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
14250 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
14260 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
14270 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
14280 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
14290 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
142a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
142b0 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  G]].** <dt>SQLIT
142c0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a  E_CONFIG_SQLLOG.
142d0 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
142e0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
142f0 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69  able if sqlite i
14300 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
14310 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
14320 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72  NABLE_SQLLOG] pr
14330 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  e-processor macr
14340 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66  o defined. The f
14350 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68  irst argument sh
14360 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69  ould.** be a poi
14370 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69  nter to a functi
14380 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28  on of type void(
14390 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
143a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  *,const char*, i
143b0 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  nt)..** The seco
143c0 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20  nd should be of 
143d0 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68  type (void*). Th
143e0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
143f0 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62  voked by the lib
14400 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65  rary.** in three
14410 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d   separate circum
14420 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66  stances, identif
14430 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65  ied by the value
14440 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
14450 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14460 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74  er. If the fourt
14470 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30  h parameter is 0
14480 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
14490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
144a0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
144b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
144c0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70  has just been op
144d0 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20  ened. The third 
144e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e  argument.** poin
144f0 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63  ts to a buffer c
14500 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61  ontaining the na
14510 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64  me of the main d
14520 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66  atabase file. If
14530 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
14540 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74  arameter is 1, t
14550 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
14560 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74  ement that the t
14570 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  hird parameter.*
14580 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20  * points to has 
14590 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74  just been execut
145a0 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66  ed. Or, if the f
145b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
145c0 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  is 2, then.** th
145d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69  e connection bei
145e0 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ng passed as the
145f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14600 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65  r is being close
14610 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  d. The.** third 
14620 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73  parameter is pas
14630 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73  sed NULL In this
14640 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70   case.  An examp
14650 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  le of using this
14660 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
14670 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  n option can be 
14680 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73  seen in the "tes
14690 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72  t_sqllog.c" sour
146a0 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68  ce file in.** th
146b0 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69  e canonical SQLi
146c0 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c  te source tree.<
146d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
146e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
146f0 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
14700 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14710 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51  _SIZE.** <dd>^SQ
14720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14730 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20  _SIZE takes two 
14740 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28  64-bit integer (
14750 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76  sqlite3_int64) v
14760 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72  alues.** that ar
14770 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d  e the default mm
14780 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74  ap size limit (t
14790 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
147a0 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d  ng for.** [PRAGM
147b0 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e  A mmap_size]) an
147c0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  d the maximum al
147d0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20  lowed mmap size 
147e0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64  limit..** ^The d
147f0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63  efault setting c
14800 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
14810 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73   by each databas
14820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69  e connection usi
14830 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65  ng.** either the
14840 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
14850 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20  ze] command, or 
14860 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  by using the.** 
14870 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
14880 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
14890 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61  ntrol.  ^(The ma
148a0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
148b0 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f  ap size.** canno
148c0 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74 20  t be changed at 
148d0 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d  run-time.  Nor m
148e0 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  ay the maximum a
148f0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
14900 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20 63  .** exceed the c
14910 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
14920 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
14930 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
14940 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
14950 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
14960 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66  option.)^.** ^If
14970 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
14980 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
14990 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
149a0 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
149b0 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
149c0 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
149d0 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  e default..** </
149e0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
149f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
14a00 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
14a10 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
14a20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14a30 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
14a40 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
14a50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14a60 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
14a70 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
14a80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14a90 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
14aa0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
14ab0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14ac0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14ad0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
14ae0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
14af0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
14b00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14b10 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
14b20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
14b30 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
14b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14b50 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
14b60 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
14b70 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
14b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
14ba0 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
14bb0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
14bc0 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
14bd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14be0 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
14bf0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
14c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14c10 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
14c20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
14c30 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
14c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14c50 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14c60 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
14c70 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14c80 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
14c90 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
14ca0 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
14cb0 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
14cc0 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
14cd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14ce0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
14cf0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
14d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14d10 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
14d20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
14d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14d40 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14d50 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
14d60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14d70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
14d80 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
14d90 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
14da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14db0 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
14dc0 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
14dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14de0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
14df0 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
14e00 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14e10 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14e30 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
14e40 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
14e50 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
14e60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14e70 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14e80 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
14e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14ea0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
14eb0 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
14ec0 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
14ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ee0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
14ef0 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
14f00 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
14f10 69 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  int64 */../*.** 
14f20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
14f30 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
14f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
14f50 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
14f60 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
14f70 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
14f80 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
14f90 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
14fa0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
14fb0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14fc0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
14fd0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14fe0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
14ff0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
15000 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
15010 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
15020 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
15030 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
15040 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
15050 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
15060 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
15070 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
15080 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
15090 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
150a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
150b0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
150c0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
150d0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
150e0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
150f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15100 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
15110 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
15120 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
15130 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
15140 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
15150 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15160 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
15170 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
15180 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
15190 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
151a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
151b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
151c0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
151d0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
151e0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
151f0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
15200 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
15210 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15220 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
15230 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
15240 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15250 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
15260 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
15270 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
15280 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
15290 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
152a0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
152b0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
152c0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
152d0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
152e0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
152f0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
15300 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
15310 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
15320 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
15330 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
15340 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
15350 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
15360 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
15370 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15380 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
15390 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
153a0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
153b0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
153c0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
153d0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
153e0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
153f0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
15400 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
15410 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
15420 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
15430 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
15440 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
15450 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
15460 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
15470 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
15480 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
15490 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
154a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
154b0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
154c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
154d0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
154e0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
154f0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
15500 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
15510 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
15520 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
15530 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
15540 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
15550 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
15560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
15570 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
15580 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
15590 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
155a0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
155b0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
155c0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
155d0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
155e0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
155f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
15600 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
15610 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
15620 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
15630 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
15640 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
15650 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
15660 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
15670 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
15680 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
15690 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
156a0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
156b0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
156c0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
156d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
156e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
156f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15700 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
15710 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
15720 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15730 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
15740 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
15750 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
15760 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
15770 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
15780 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
15790 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
157a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
157b0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
157c0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
157d0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
157e0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
157f0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
15800 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
15810 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
15820 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
15830 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
15840 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15850 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
15860 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
15870 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
15880 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
15890 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
158a0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
158b0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
158c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
158d0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
158e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
158f0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
15900 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
15910 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
15920 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
15930 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15940 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15950 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15960 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
15970 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
15980 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
15990 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
159a0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
159b0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
159c0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
159d0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
159e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
159f0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
15a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15a10 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
15a20 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15a30 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
15a40 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
15a50 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
15a60 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
15a70 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
15a80 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
15a90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15aa0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15ab0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
15ac0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
15ad0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
15ae0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
15af0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
15b00 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
15b10 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
15b20 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
15b30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
15b40 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
15b50 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
15b60 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
15b70 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
15b80 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
15b90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
15ba0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
15bb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15bc0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
15bd0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
15be0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15bf0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
15c00 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
15c10 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
15c20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15c30 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
15c40 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
15c50 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
15c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15c70 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
15c80 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
15c90 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
15ca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
15cb0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
15cc0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
15cd0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
15ce0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
15cf0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
15d00 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
15d10 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
15d20 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
15d30 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
15d40 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
15d50 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
15d60 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ility..*/.SQLITE
15d70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
15d80 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
15d90 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
15da0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
15db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
15dc0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
15dd0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
15de0 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
15df0 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
15e00 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
15e10 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
15e20 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
15e30 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
15e40 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
15e50 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
15e60 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
15e70 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
15e80 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
15e90 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
15ea0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
15eb0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
15ec0 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
15ed0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
15ee0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
15ef0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
15f00 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
15f10 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
15f20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
15f30 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
15f40 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
15f50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
15f60 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
15f70 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
15f80 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
15f90 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
15fa0 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
15fb0 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
15fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15fd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
15fe0 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41  st argument.  ^A
15ff0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
16000 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20  ion 3.7.7, this 
16010 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f  routines.** reco
16020 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  rds the last ins
16030 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74  ert rowid of bot
16040 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65  h ordinary table
16050 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74  s and [virtual t
16060 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e  ables]..** ^If n
16070 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
16080 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
16090 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
160a0 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
160b0 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
160c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
160d0 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
160e0 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
160f0 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
16100 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
16110 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
16120 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
16130 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
16140 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
16150 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
16160 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
16170 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16180 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
16190 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
161a0 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
161b0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
161c0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
161d0 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
161e0 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
161f0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
16200 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
16210 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
16220 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
16230 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
16240 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
16250 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
16260 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
16270 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
16280 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
16290 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
162a0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
162b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
162c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
162d0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
162e0 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
162f0 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
16300 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
16310 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
16320 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
16330 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
16340 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
16350 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
16360 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
16370 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
16380 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
16390 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
163a0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
163b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
163c0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
163d0 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
163e0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
163f0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
16400 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
16410 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
16420 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
16430 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
16440 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
16450 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
16460 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
16470 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
16480 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
16490 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
164a0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
164b0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
164c0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
164d0 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
164e0 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
164f0 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
16500 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
16510 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
16520 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
16530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
16540 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
16550 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
16560 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16570 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16580 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
16590 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
165a0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
165b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
165c0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
165d0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
165e0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
165f0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
16600 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
16610 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
16620 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
16630 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
16640 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16650 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16660 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
16670 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
16680 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
16690 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
166a0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
166b0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
166c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
166d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
166e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
166f0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
16700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16710 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
16720 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
16730 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
16740 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
16750 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16760 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
16770 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
16780 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
16790 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
167a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
167b0 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
167c0 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
167d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
167e0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
167f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
16800 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
16810 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
16820 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
16830 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
16840 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
16850 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
16860 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
16870 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
16880 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
16890 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
168a0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
168b0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
168c0 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
168d0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
168e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
168f0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
16900 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
16910 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
16920 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
16930 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
16940 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
16950 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
16960 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
16970 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
16980 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
16990 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
169a0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
169b0 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
169c0 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
169d0 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
169e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
169f0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
16a00 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
16a10 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
16a20 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
16a30 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
16a40 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
16a50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
16a60 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
16a70 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
16a80 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
16a90 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
16aa0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
16ab0 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
16ac0 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
16ad0 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
16ae0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
16af0 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
16b00 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
16b10 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
16b20 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
16b30 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
16b40 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
16b50 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
16b60 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
16b70 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
16b80 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16b90 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
16ba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16bb0 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
16bc0 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
16bd0 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
16be0 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
16bf0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
16c00 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
16c10 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
16c20 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
16c30 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16c40 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
16c50 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
16c60 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
16c70 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
16c80 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
16c90 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
16ca0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
16cb0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
16cc0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
16cd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16ce0 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
16cf0 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
16d00 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
16d10 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16d20 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16d30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16d40 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
16d50 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
16d60 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
16d70 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16d80 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
16d90 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
16da0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16db0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
16dc0 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
16dd0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
16de0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
16df0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
16e00 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
16e10 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
16e20 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
16e30 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
16e40 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
16e50 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
16e60 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
16e70 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
16e80 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
16e90 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
16ea0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
16eb0 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
16ec0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
16ed0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
16ee0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
16ef0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
16f00 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16f10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
16f20 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
16f30 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
16f40 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
16f50 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
16f60 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
16f70 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
16f80 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
16f90 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
16fa0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
16fb0 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
16fc0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
16fd0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16fe0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
16ff0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17000 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17010 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
17020 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17030 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17040 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17050 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17060 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17070 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17080 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
17090 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
170a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
170b0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
170c0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
170d0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
170e0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
170f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  I int sqlite3_ch
17100 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
17110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17120 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
17130 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
17140 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17150 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17160 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
17170 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
17180 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
17190 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
171a0 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
171b0 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
171c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
171d0 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
171e0 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
171f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
17200 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
17210 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
17220 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
17230 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17240 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
17250 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
17260 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
17270 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
17280 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
17290 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
172a0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
172b0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
172c0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
172d0 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
172e0 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
172f0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
17300 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
17310 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
17320 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
17330 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
17340 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
17350 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
17360 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
17370 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
17380 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
17390 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
173a0 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
173b0 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
173c0 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
173d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
173e0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
173f0 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
17400 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
17410 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
17420 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
17430 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
17440 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
17450 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
17460 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
17470 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
17480 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
17490 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
174a0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
174b0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
174c0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
174d0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
174e0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
174f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
17500 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
17510 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
17520 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
17530 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
17540 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17550 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
17560 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
17570 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
17580 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
17590 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
175a0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
175b0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
175c0 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
175d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  I int sqlite3_to
175e0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
175f0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17600 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
17610 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
17620 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
17630 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
17640 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
17650 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
17660 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
17670 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
17680 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
17690 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
176a0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
176b0 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
176c0 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
176d0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
176e0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
176f0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
17700 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
17710 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
17720 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
17730 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
17740 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
17750 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
17760 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
17770 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
17780 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
17790 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
177a0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
177b0 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
177c0 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
177d0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
177e0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
177f0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
17800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
17810 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
17820 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
17830 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
17840 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
17850 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
17860 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
17870 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
17880 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
17890 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
178a0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
178b0 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
178c0 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
178d0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
178e0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
178f0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
17900 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
17910 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
17920 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
17930 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
17940 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
17950 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
17960 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
17970 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
17980 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
17990 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
179a0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
179b0 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
179c0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
179d0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
179e0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
179f0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
17a00 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
17a10 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
17a20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17a30 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
17a40 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
17a50 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
17a60 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
17a70 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
17a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
17a90 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
17aa0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
17ab0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17ac0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17ad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17ae0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
17af0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
17b00 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
17b10 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
17b20 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
17b30 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
17b40 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
17b50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
17b60 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
17b70 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
17b80 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17b90 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17ba0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
17bb0 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
17bc0 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
17bd0 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
17be0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
17bf0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
17c00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17c10 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
17c20 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
17c30 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
17c40 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
17c50 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
17c60 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
17c70 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
17c80 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17c90 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17ca0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17cb0 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
17cc0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
17cd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17ce0 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
17cf0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
17d00 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
17d10 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
17d20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
17d30 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51  ly happen..*/.SQ
17d40 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
17d50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17d60 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17d70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
17d80 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
17d90 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
17da0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
17db0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
17dc0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
17dd0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
17de0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
17df0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
17e00 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
17e10 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
17e20 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
17e30 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
17e40 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
17e50 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
17e60 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
17e70 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
17e80 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
17e90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17ea0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
17eb0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
17ec0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
17ed0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
17ee0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
17ef0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
17f00 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
17f10 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
17f20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
17f30 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
17f40 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
17f50 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
17f60 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
17f70 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
17f80 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
17f90 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
17fa0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
17fb0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
17fc0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
17fd0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
17fe0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
17ff0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
18000 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
18010 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
18020 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
18030 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
18040 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
18050 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
18060 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
18070 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
18080 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
18090 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
180a0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
180b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
180c0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
180d0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
180e0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
180f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18100 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
18110 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
18120 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
18130 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
18140 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
18150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
18160 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
18170 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
18180 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
18190 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
181a0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
181b0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
181c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
181d0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
181e0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
181f0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
18200 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
18210 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18220 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
18230 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
18240 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18250 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
18260 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
18270 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
18280 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
18290 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
182a0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
182b0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
182c0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
182d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
182e0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
182f0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
18300 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18310 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
18320 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18330 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
18340 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
18350 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18360 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18370 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
18380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18390 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
183a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
183b0 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
183c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
183d0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
183e0 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f  r *sql);.SQLITE_
183f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
18400 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
18410 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
18420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
18430 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
18440 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
18450 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
18460 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18470 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
18480 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
18490 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
184a0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
184b0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
184c0 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
184d0 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
184e0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
184f0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
18500 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
18510 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
18520 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
18530 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
18540 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18550 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
18560 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
18570 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
18580 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
18590 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
185a0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
185b0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
185c0 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
185d0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
185e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
185f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
18600 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
18610 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
18620 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
18630 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
18640 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
18650 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
18660 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18670 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
18680 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
18690 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
186a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
186b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
186c0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
186d0 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
186e0 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
186f0 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
18700 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
18710 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
18720 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
18730 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
18740 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
18750 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
18760 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
18770 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
18780 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
18790 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
187a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
187b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
187c0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
187d0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
187e0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
187f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
18800 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
18810 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
18820 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
18830 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
18840 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
18850 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
18860 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
18870 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
18880 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
18890 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
188a0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
188b0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
188c0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
188d0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
188e0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
188f0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
18900 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
18910 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
18920 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
18930 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
18940 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18950 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
18960 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
18970 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
18980 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
18990 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
189a0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
189b0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
189c0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
189d0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
189e0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
189f0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
18a00 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
18a10 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
18a20 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
18a30 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
18a40 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
18a50 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
18a60 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
18a70 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
18a80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
18a90 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
18aa0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18ab0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
18ac0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
18ad0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
18ae0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
18af0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
18b00 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
18b10 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
18b20 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
18b30 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
18b40 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
18b50 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
18b60 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
18b70 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
18b80 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
18b90 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
18ba0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
18bb0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
18bc0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
18bd0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
18be0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
18bf0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
18c00 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
18c10 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
18c20 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
18c30 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
18c40 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
18c50 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
18c60 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
18c70 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
18c80 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
18c90 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
18ca0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
18cb0 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
18cc0 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
18cd0 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
18ce0 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
18cf0 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
18d00 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
18d10 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
18d20 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
18d30 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
18d40 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
18d50 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
18d60 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
18d70 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
18d80 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
18d90 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
18da0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
18db0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
18dc0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
18dd0 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
18de0 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
18df0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
18e00 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
18e10 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
18e20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
18e30 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
18e40 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
18e50 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
18e60 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18e70 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
18e80 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
18e90 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
18ea0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
18eb0 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
18ec0 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
18ed0 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
18ee0 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
18ef0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
18f00 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
18f10 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
18f20 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
18f30 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
18f40 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
18f50 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
18f60 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
18f70 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
18f80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
18f90 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
18fa0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18fb0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
18fc0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
18fd0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
18fe0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
18ff0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
19000 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
19010 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
19020 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
19030 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
19040 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
19050 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
19060 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
19070 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
19080 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
19090 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
190a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
190b0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
190c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
190d0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
190e0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
190f0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
19100 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
19110 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
19120 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
19130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19140 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
19150 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
19160 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19170 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
19180 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
19190 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
191a0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
191b0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
191c0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
191d0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
191e0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
191f0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
19200 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
19210 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
19220 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
19230 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
19240 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
19250 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
19260 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
19270 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
19280 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
19290 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
192a0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
192b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
192c0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
192d0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
192e0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
192f0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19300 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
19310 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
19320 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
19330 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
19340 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
19350 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
19360 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
19370 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
19380 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
19390 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
193a0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
193b0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
193c0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
193d0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
193e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
193f0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
19400 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
19410 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
19420 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
19440 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
19450 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
19460 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
19470 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
19480 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
19490 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
194a0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
194b0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
194c0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
194d0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
194e0 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ed.)^.*/.SQLITE_
194f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
19500 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
19510 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
19520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19530 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
19540 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
19550 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
19560 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
19570 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
19580 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
19590 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
195a0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
195b0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
195c0 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
195d0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
195e0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
195f0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
19600 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
19610 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
19620 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
19630 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
19640 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
19650 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
19660 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
19670 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
19680 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
19690 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
196a0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
196b0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
196c0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
196d0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
196e0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
196f0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
19700 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19710 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
19720 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
19730 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
19740 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
19750 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
19760 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
19770 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
19780 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
19790 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
197a0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
197b0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
197c0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
197d0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
197e0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
197f0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
19800 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
19810 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
19820 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19830 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
19840 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
19850 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
19860 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
19870 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
19880 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
19890 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
198a0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
198b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
198c0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
198d0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
198e0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
198f0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
19900 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
19910 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
19920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
19930 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
19940 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
19950 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
19960 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
19970 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
19980 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
19990 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
199a0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
199b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
199c0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
199d0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
199e0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
199f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
19a00 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
19a10 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
19a20 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
19a30 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
19a40 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
19a50 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
19a60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
19a70 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
19a80 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
19a90 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
19aa0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
19ab0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
19ac0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
19ad0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
19ae0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
19af0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
19b00 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
19b10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19b20 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
19b30 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
19b40 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
19b50 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
19b60 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
19b70 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
19b80 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
19b90 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
19ba0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
19bb0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
19bc0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
19bd0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
19be0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
19bf0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
19c00 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19c10 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
19c20 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
19c30 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
19c40 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
19c50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
19c60 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
19c70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19c80 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
19c90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19ca0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
19cb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19cc0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
19cd0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
19ce0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
19cf0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
19d00 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19d10 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
19d20 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
19d30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
19d40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19d50 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
19d60 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
19d70 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
19d80 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
19d90 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
19da0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
19db0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
19dc0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
19dd0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
19de0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
19df0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
19e00 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
19e10 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
19e20 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
19e30 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
19e40 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
19e50 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
19e60 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
19e70 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
19e80 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19e90 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
19ea0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19eb0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
19ec0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
19ed0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
19ee0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
19ef0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
19f00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
19f10 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
19f20 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
19f30 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
19f40 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
19f50 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
19f60 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
19f70 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
19f80 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
19f90 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
19fa0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
19fb0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
19fc0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
19fd0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
19fe0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19ff0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1a000 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1a010 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1a020 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a030 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1a040 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1a050 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1a060 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1a070 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1a080 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1a090 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1a0a0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1a0b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1a0c0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1a0d0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1a0e0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1a0f0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1a100 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1a110 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1a120 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1a130 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1a140 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1a150 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1a160 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1a170 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1a180 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1a190 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1a1a0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1a1b0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1a1c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1a1d0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1a1e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a1f0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1a200 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1a210 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1a220 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1a230 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1a240 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1a250 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1a260 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a270 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1a280 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1a290 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1a2a0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a2b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1a2c0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1a2d0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1a2e0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1a2f0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1a300 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
1a310 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
1a320 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1a330 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1a340 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1a350 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1a360 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1a370 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a380 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1a390 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1a3a0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1a3b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1a3c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1a3d0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
1a3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1a3f0 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1a400 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1a410 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1a420 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1a430 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1a440 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1a450 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1a460 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1a470 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1a480 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1a490 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1a4a0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1a4b0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1a4c0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1a4d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1a4e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a4f0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1a500 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1a510 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1a520 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1a530 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1a540 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1a550 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1a560 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1a570 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1a580 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1a590 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1a5a0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1a5b0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1a5c0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1a5d0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a5e0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1a5f0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1a600 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a610 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1a620 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1a630 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1a640 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1a650 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1a660 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1a670 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1a680 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1a690 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1a6a0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1a6b0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1a6c0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1a6d0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1a6e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1a6f0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1a700 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1a710 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1a720 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1a730 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1a740 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1a750 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1a760 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1a770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1a780 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1a790 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1a7a0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1a7b0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1a7c0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1a7d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1a7e0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1a7f0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1a800 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1a810 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1a820 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1a830 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1a840 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1a850 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1a860 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1a870 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1a880 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1a890 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1a8a0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1a8b0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1a8c0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1a8d0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1a8e0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1a8f0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1a900 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1a910 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1a920 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1a930 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1a940 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1a950 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1a960 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1a970 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1a980 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1a990 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1a9a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1a9b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a9c0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1a9d0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1a9e0 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1a9f0 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1aa00 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1aa10 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1aa20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1aa30 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1aa40 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1aa50 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1aa60 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1aa70 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1aa80 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1aa90 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1aaa0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1aab0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1aac0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1aad0 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1aae0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1aaf0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1ab00 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1ab10 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1ab20 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1ab30 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1ab40 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1ab50 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1ab60 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1ab70 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1ab80 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1ab90 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1aba0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1abb0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1abc0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1abd0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1abe0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1abf0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1ac00 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1ac10 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1ac20 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ac30 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ac40 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1ac50 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1ac60 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1ac70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ac80 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1ac90 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1aca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1acb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1acc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1acd0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1ace0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1acf0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1ad00 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1ad10 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1ad20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1ad30 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1ad40 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1ad50 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1ad60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ad70 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1ad80 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1ad90 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1ada0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1adb0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1adc0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1add0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1ade0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1adf0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ae00 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1ae10 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1ae20 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1ae30 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1ae40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ae50 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1ae60 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1ae70 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1ae80 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1ae90 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1aea0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1aeb0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1aec0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1aed0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1aee0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1aef0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1af00 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1af10 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1af20 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1af30 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1af40 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1af50 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1af60 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1af70 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1af80 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1af90 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1afa0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1afb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1afc0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1afd0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1afe0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1aff0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1b000 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1b010 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1b020 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1b030 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1b040 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1b050 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1b060 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1b070 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1b080 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1b090 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1b0a0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1b0b0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1b0c0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1b0d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b0e0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b0f0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1b100 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1b110 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1b120 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1b130 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b140 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b150 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b160 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b170 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b180 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1b190 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1b1a0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1b1b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1b1c0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1b1d0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1b1e0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1b1f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1b200 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1b210 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1b220 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1b230 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1b240 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1b250 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1b260 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1b270 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1b280 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1b290 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b2a0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1b2b0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1b2c0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1b2d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1b2e0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1b2f0 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  *,...);.SQLITE_A
1b300 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1b310 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1b320 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1b330 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1b340 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b350 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b360 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b370 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1b380 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1b390 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b3a0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1b3b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1b3c0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1b3d0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1b3e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1b3f0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1b400 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1b410 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1b420 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1b430 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b440 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1b450 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1b460 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1b470 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1b480 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1b490 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1b4a0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1b4b0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1b4c0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1b4d0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1b4e0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1b4f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1b500 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b510 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1b520 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1b530 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1b540 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1b550 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1b560 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1b570 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1b580 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b590 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1b5a0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1b5b0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1b5c0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1b5d0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1b5e0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1b5f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1b600 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1b610 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1b620 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b630 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1b640 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1b650 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1b660 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1b670 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1b680 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1b690 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1b6a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1b6b0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1b6c0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1b6d0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1b6e0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1b6f0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1b700 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1b710 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1b720 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1b730 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1b740 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1b750 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1b760 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1b770 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1b780 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1b790 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1b7a0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1b7b0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1b7c0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1b7d0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1b7e0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1b7f0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1b800 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1b810 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1b820 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1b830 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1b840 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1b850 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1b860 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1b870 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1b880 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1b890 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1b8a0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1b8b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1b8c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1b8d0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1b8e0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  c()..**.** ^(The
1b8f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b900 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
1b910 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1b920 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1b930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1b940 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1b950 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
1b960 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
1b970 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
1b980 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b990 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
1b9a0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
1b9b0 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20  rameter.)^ ^ If 
1b9c0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1b9d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b9e0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1b9f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1ba00 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
1ba10 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
1ba20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ba30 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
1ba40 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1ba50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1ba60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ba70 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65  )..** ^If the se
1ba80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1ba90 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1baa0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
1bab0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
1bac0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1bad0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
1bae0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
1baf0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
1bb00 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
1bb10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1bb20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bb30 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  ()..** ^sqlite3_
1bb40 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1bb50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1bb60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1bb70 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1bb80 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1bb90 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
1bba0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
1bbb0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
1bbc0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1bbd0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1bbe0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1bbf0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1bc00 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1bc10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1bc20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1bc30 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1bc40 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1bc50 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1bc60 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
1bc70 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1bc80 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1bc90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bca0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
1bcb0 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
1bcc0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
1bcd0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
1bce0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75  ^The memory retu
1bcf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1bd00 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
1bd10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
1bd20 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1bd30 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1bd40 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1bd50 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1bd60 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1bd70 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1bd80 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1bd90 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1bda0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1bdb0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1bdc0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1bdd0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1bde0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1bdf0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1be00 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1be10 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1be20 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1be30 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1be40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1be50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1be60 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1be70 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1be80 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1be90 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1bea0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1beb0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1bec0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1bed0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1bee0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1bef0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1bf00 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1bf10 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1bf20 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1bf30 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1bf40 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1bf50 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1bf60 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1bf70 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1bf80 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1bf90 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1bfa0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1bfb0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1bfc0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1bfd0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1bfe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1bff0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1c000 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1c010 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1c020 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1c030 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1c040 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1c050 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1c060 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1c070 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1c080 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1c090 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1c0a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c0b0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1c0c0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1c0d0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1c0e0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1c0f0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1c100 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1c110 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1c120 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1c130 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1c140 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1c150 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1c160 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1c170 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1c180 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1c190 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1c1a0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1c1b0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1c1c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c1d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1c1e0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
1c1f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1c200 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1c210 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1c220 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1c230 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1c240 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1c250 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1c260 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c270 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1c280 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1c290 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1c2a0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1c2b0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1c2c0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1c2d0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1c2e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1c2f0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1c300 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1c310 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c320 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1c330 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1c340 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1c350 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1c360 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1c370 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c380 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1c390 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1c3a0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1c3b0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1c3c0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1c3d0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1c3e0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1c3f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1c400 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1c410 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1c420 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1c430 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1c440 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1c450 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1c460 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1c470 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1c480 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1c490 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c4a0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1c4b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c4c0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1c4d0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1c4e0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1c4f0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1c500 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1c510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c520 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1c530 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1c540 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1c550 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1c560 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1c570 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1c580 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1c590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1c5a0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1c5b0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1c5c0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1c5d0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1c5e0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1c5f0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1c600 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1c610 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c620 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1c630 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1c640 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1c650 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c660 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1c670 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1c680 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1c690 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1c6a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1c6b0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1c6c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1c6d0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
1c6e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1c6f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1c700 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1c710 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1c720 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1c730 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1c740 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1c750 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1c760 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1c770 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1c780 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1c790 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1c7a0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1c7b0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1c7c0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1c7d0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1c7e0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1c7f0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1c800 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1c810 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1c820 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1c830 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1c840 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1c850 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1c860 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1c870 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1c880 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1c890 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1c8a0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1c8b0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1c8c0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1c8d0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1c8e0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1c8f0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1c900 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1c910 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1c920 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1c930 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1c940 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1c950 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1c960 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1c970 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1c980 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1c990 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1c9a0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1c9b0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1c9c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1c9d0 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1c9e0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1c9f0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1ca00 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1ca10 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1ca20 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1ca30 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1ca40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1ca50 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1ca60 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
1ca70 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1ca80 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1ca90 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1caa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cab0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1cac0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1cad0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1cae0 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1caf0 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1cb00 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1cb10 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1cb20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cb30 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1cb40 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1cb50 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1cb60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cb70 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1cb80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1cb90 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1cba0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1cbb0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1cbc0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1cbd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cbe0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1cbf0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1cc00 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1cc10 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1cc20 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1cc30 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1cc40 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1cc50 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1cc60 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1cc70 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1cc80 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1cc90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1cca0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1ccb0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1ccc0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1ccd0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1cce0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ccf0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1cd00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1cd10 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1cd20 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1cd30 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1cd40 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1cd50 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1cd60 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1cd70 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1cd80 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1cd90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1cda0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1cdb0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1cdc0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1cdd0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1cde0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1cdf0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ce00 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1ce10 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1ce20 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1ce30 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1ce40 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1ce50 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1ce60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ce70 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1ce80 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1ce90 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1cea0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1ceb0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1cec0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1ced0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1cee0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1cef0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1cf00 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1cf10 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1cf20 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1cf30 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1cf40 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1cf50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1cf60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1cf70 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1cf80 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1cf90 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1cfa0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1cfb0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1cfc0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1cfd0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1cfe0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1cff0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d000 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1d010 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1d020 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1d030 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1d040 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1d050 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1d060 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1d070 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d080 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1d090 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1d0a0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1d0b0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1d0c0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1d0d0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1d0e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1d0f0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1d100 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1d110 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1d120 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1d130 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1d140 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1d150 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1d160 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1d170 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1d180 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1d190 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1d1a0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1d1b0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1d1c0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1d1d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d1e0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1d1f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1d200 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1d210 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1d220 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1d230 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1d240 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1d250 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1d260 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1d270 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1d280 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1d290 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1d2a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d2b0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1d2c0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1d2d0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1d2e0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1d2f0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1d300 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1d310 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1d320 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1d330 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1d340 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1d350 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1d360 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1d370 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1d380 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1d390 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1d3a0 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1d3b0 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1d3c0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1d3d0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1d3e0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1d3f0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1d400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1d410 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1d420 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1d430 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1d440 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1d450 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1d460 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1d470 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1d480 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1d490 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1d4a0 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1d4b0 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1d4c0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1d4d0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1d4e0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1d4f0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1d500 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1d510 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1d520 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1d530 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1d540 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1d550 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1d560 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1d570 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1d580 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1d590 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1d5a0 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1d5b0 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1d5c0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1d5d0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1d5e0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1d5f0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1d600 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1d610 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1d620 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1d630 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1d640 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1d650 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1d660 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1d670 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1d680 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1d690 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1d6a0 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1d6b0 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1d6c0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1d6d0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1d6e0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1d6f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1d700 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1d710 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1d720 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1d730 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1d740 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1d750 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1d760 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1d770 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1d780 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1d790 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1d7a0 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1d7b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1d7c0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1d7d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1d7e0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1d7f0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1d800 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1d810 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1d820 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1d830 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1d840 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1d850 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1d860 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1d870 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1d880 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1d890 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1d8a0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1d8b0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1d8c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1d8d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1d8e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d8f0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1d900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d910 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1d920 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1d930 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1d940 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1d950 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1d960 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1d970 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1d980 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1d990 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d9a0 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1d9b0 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1d9c0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1d9d0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1d9e0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1d9f0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1da00 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1da10 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1da20 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1da30 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1da40 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1da50 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1da60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1da70 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1da80 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1da90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1daa0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1dab0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1dac0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1dad0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1dae0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1daf0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1db00 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1db10 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1db20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1db30 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1db40 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1db50 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1db60 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1db70 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1db80 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1db90 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1dba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1dbb0 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1dbc0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1dbd0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1dbe0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49   change..*/.SQLI
1dbf0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1dc00 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1dc10 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
1dc20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
1dc30 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
1dc40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1dc50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1dc60 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
1dc70 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
1dc80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dc90 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
1dca0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1dcb0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1dcc0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1dcd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dce0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
1dcf0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
1dd00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
1dd10 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
1dd20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
1dd30 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
1dd40 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
1dd50 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
1dd60 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
1dd70 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
1dd80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1dd90 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1dda0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
1ddb0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1ddc0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1ddd0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
1dde0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61  LITE_IGNORE is a
1ddf0 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53  lso used as a [S
1de00 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c  QLITE_ROLLBACK |
1de10 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a   return code].**
1de20 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
1de30 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
1de40 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
1de50 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
1de60 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
1de70 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
1de80 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
1de90 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
1dea0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
1deb0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
1dec0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
1ded0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
1dee0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
1def0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1df00 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
1df10 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1df20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1df30 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
1df40 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
1df50 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1df60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
1df70 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
1df80 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
1df90 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
1dfa0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1dfb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1dfc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1dfd0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
1dfe0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
1dff0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
1e000 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
1e010 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
1e020 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
1e030 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
1e040 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e050 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
1e060 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
1e070 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
1e080 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
1e090 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
1e0a0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
1e0b0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
1e0c0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
1e0d0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
1e0e0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
1e0f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
1e100 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1e110 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1e120 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
1e130 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
1e140 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1e150 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1e160 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
1e170 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
1e180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e190 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
1e1a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
1e1b0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
1e1c0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
1e1d0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
1e1e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1e1f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e200 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
1e210 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
1e220 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1e230 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1e240 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1e250 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
1e260 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
1e270 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
1e280 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
1e290 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
1e2a0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1e2b0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1e2c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e2d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1e2e0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1e2f0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1e300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e310 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1e320 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1e330 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1e340 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e360 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1e370 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1e380 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e390 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e3b0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1e3c0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1e3d0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1e3e0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e400 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1e410 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1e420 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e430 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e440 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e450 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1e460 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1e470 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1e480 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e490 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e4a0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1e4b0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1e4c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1e4d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e4e0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e4f0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1e500 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1e510 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1e520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e530 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1e540 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1e550 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1e560 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e580 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1e590 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1e5a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e5b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e5d0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1e5e0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1e5f0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1e600 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e620 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1e630 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1e640 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1e650 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e670 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1e680 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1e690 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1e6a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e6c0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1e6d0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1e6e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e6f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e710 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1e720 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1e730 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1e740 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e760 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1e770 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1e780 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1e790 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e7b0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1e7c0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1e7d0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1e7e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e800 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1e810 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1e820 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1e830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1e850 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1e860 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1e870 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e880 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1e8a0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1e8b0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1e8c0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1e8d0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1e8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1e8f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e900 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1e910 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1e920 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1e930 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1e940 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1e950 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1e960 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1e970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e980 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1e990 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1e9a0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1e9b0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1e9c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e9d0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1e9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1e9f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ea00 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1ea10 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ea20 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1ea30 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1ea40 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1ea50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ea60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ea70 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1ea90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1eaa0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1eab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eac0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1ead0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1eae0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1eaf0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1eb00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eb10 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1eb20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1eb30 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1eb40 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1eb50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1eb60 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1eb70 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1eb80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1eb90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1eba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ebb0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1ebc0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1ebd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ebe0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1ebf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ec00 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1ec10 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1ec20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1ec30 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1ec40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ec50 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1ec60 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1ec70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1ec80 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1ec90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eca0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1ecb0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1ecc0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1ecd0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1ece0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ecf0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1ed00 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1ed10 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1ed20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1ed30 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1ed40 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1ed50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1ed60 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1ed70 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1ed80 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1ed90 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1eda0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1edb0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1edc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1edd0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1ede0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1edf0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1ee00 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1ee10 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1ee20 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1ee30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1ee40 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1ee50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1ee60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ee70 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1ee80 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1ee90 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1eea0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1eeb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1eec0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1eed0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1eee0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1eef0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1ef00 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1ef10 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1ef20 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1ef30 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1ef40 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1ef50 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1ef60 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1ef70 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1ef80 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1ef90 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1efa0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
1efb0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
1efc0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
1efd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
1efe0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
1eff0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
1f000 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
1f010 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
1f020 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
1f030 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1f040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1f050 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1f060 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1f070 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1f080 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1f090 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1f0a0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
1f0b0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1f0c0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
1f0d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1f0e0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
1f0f0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
1f100 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
1f110 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
1f120 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
1f130 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
1f140 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1f150 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
1f160 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
1f170 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
1f180 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
1f190 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
1f1a0 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
1f1b0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
1f1c0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
1f1d0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
1f1e0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
1f1f0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
1f200 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
1f210 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1f220 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
1f230 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
1f240 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
1f250 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
1f260 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
1f270 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
1f280 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
1f290 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
1f2a0 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
1f2b0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1f2c0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1f2d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
1f2e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1f2f0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1f300 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1f310 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1f320 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1f330 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
1f340 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1f350 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1f360 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1f370 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1f380 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1f390 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1f3a0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1f3b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1f3c0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1f3d0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1f3e0 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
1f3f0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
1f400 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
1f410 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
1f420 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
1f430 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
1f440 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1f450 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
1f460 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
1f470 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1f480 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1f490 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
1f4a0 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
1f4b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f4c0 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
1f4d0 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1f4e0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1f4f0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1f500 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1f510 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1f520 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1f530 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
1f540 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
1f550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f560 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
1f570 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
1f580 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
1f590 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e  he approximate n
1f5a0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1f5b0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1f5c0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1f5d0 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1f5e0 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1f5f0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1f600 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1f610 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65   X.  ^If N is le
1f620 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e  ss than one then
1f630 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a   the progress.**
1f640 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61   handler is disa
1f650 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  bled..**.** ^Onl
1f660 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72  y a single progr
1f670 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20  ess handler may 
1f680 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e  be defined at on
1f690 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64  e time per.** [d
1f6a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f6b0 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e  on]; setting a n
1f6c0 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  ew progress hand
1f6d0 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a  ler cancels the.
1f6e0 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65  ** old one.  ^Se
1f6f0 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  tting parameter 
1f700 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c  X to NULL disabl
1f710 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  es the progress 
1f720 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65  handler..** ^The
1f730 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f740 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c  r is also disabl
1f750 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20  ed by setting N 
1f760 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a  to a value less.
1f770 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a  ** than 1..**.**
1f780 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
1f790 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1f7a0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1f7b0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1f7c0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1f7d0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1f7e0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1f7f0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1f800 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1f810 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1f820 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1f830 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f840 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1f850 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1f860 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1f870 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1f880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1f890 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1f8a0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1f8b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1f8c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f8d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1f8e0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1f8f0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1f900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f910 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1f920 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1f930 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1f940 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ..**.*/.SQLITE_A
1f950 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
1f960 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1f970 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
1f980 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
1f990 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1f9a0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
1f9b0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
1f9c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
1f9d0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1f9e0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1f9f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
1fa00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1fa10 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
1fa20 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1fa30 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1fa40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1fa50 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1fa60 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1fa70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1fa80 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1fa90 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1faa0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1fab0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1fac0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1fad0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1fae0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1faf0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1fb00 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1fb10 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1fb20 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1fb30 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1fb40 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1fb50 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1fb60 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1fb70 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1fb80 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1fb90 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1fba0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1fbb0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1fbc0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1fbd0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1fbe0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1fbf0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1fc00 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1fc10 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1fc20 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1fc30 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1fc40 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1fc50 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1fc60 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1fc70 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1fc80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1fc90 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1fca0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1fcb0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1fcc0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1fcd0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1fce0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1fcf0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1fd00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1fd10 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1fd20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1fd30 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1fd40 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1fd50 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1fd60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1fd70 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1fd80 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1fd90 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1fda0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1fdb0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1fdc0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1fdd0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1fde0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1fdf0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1fe00 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1fe10 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1fe20 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1fe30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fe40 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1fe50 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1fe60 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1fe70 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1fe80 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1fe90 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1fea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1feb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1fec0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1fed0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1fee0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1fef0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1ff00 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1ff10 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1ff20 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1ff30 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1ff40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1ff50 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1ff60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1ff70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ff80 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1ff90 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1ffa0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1ffb0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1ffc0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1ffd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1ffe0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1fff0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
20000 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20010 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
20020 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
20030 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
20040 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
20050 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
20060 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
20070 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20080 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
20090 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
200a0 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
200b0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
200c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
200d0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
200e0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
200f0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
20100 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20110 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
20120 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
20130 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20140 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20150 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20160 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
20170 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
20180 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
20190 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
201a0 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
201b0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
201c0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
201d0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
201e0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
201f0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
20200 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
20210 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
20220 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
20230 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
20240 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
20250 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
20260 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20270 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
20280 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
20290 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
202a0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
202b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
202c0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
202d0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
202e0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
202f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20300 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
20310 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
20320 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
20330 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
20340 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20350 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
20360 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
20370 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
20380 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
20390 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
203a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
203b0 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
203c0 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
203d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
203e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
203f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
20400 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
20410 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
20420 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
20430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20440 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
20450 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
20460 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
20470 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
20480 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
20490 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
204a0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
204b0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
204c0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
204d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
204e0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
204f0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
20500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20510 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
20520 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
20530 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
20540 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
20550 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
20560 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
20570 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
20580 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
20590 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
205a0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
205b0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
205c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
205d0 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
205e0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
205f0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
20600 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
20610 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
20620 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
20630 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
20640 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
20650 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
20660 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
20670 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20680 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
20690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
206a0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
206b0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
206c0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
206d0 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
206e0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
206f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
20700 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20710 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
20720 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
20730 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
20740 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
20750 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
20760 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
20770 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
20780 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
20790 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
207a0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
207b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
207c0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
207d0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
207e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
207f0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
20800 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
20810 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
20820 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
20830 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
20840 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
20850 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
20860 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
20870 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
20880 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
20890 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
208a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
208b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
208c0 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
208d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
208e0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
208f0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
20900 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
20910 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
20920 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
20930 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
20940 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
20950 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
20960 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
20970 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
20980 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
20990 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
209a0 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
209b0 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
209c0 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
209d0 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
209e0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
209f0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
20a00 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
20a10 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
20a20 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
20a30 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
20a40 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
20a50 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
20a60 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
20a70 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
20a80 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
20a90 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
20aa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
20ab0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
20ac0 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
20ad0 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
20ae0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
20af0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
20b00 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
20b10 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
20b20 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
20b30 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
20b40 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
20b50 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
20b60 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
20b70 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
20b80 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
20b90 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
20ba0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
20bb0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
20bc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20bd0 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
20be0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
20bf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
20c00 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69  _open_v2(), or i
20c10 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e  f it has.** been
20c20 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c   enabled globall
20c30 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  y using the [SQL
20c40 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20  ITE_CONFIG_URI] 
20c50 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a  option with the.
20c60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
20c70 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20  ig()] method or 
20c80 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  by the [SQLITE_U
20c90 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d  SE_URI] compile-
20ca0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
20cb0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
20cc0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20  sion 3.7.7, URI 
20cd0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
20ce0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65  etation is turne
20cf0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61  d off.** by defa
20d00 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20  ult, but future 
20d10 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
20d20 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20  te might enable 
20d30 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  URI filename.** 
20d40 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62  interpretation b
20d50 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20  y default.  See 
20d60 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d  "[URI filenames]
20d70 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  " for additional
20d80 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
20d90 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  .**.** URI filen
20da0 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20  ames are parsed 
20db0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43  according to RFC
20dc0 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55   3986. ^If the U
20dd0 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a  RI contains an.*
20de0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65  * authority, the
20df0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74  n it must be eit
20e00 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72  her an empty str
20e10 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e  ing or the strin
20e20 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74  g .** "localhost
20e30 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  ". ^If the autho
20e40 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65  rity is not an e
20e50 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22  mpty string or "
20e60 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a  localhost", an .
20e70 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  ** error is retu
20e80 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c  rned to the call
20e90 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e  er. ^The fragmen
20ea0 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
20eb0 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65   URI, if .** pre
20ec0 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64  sent, is ignored
20ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
20ee0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f  uses the path co
20ef0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55  mponent of the U
20f00 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f  RI as the name o
20f10 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a  f the disk file.
20f20 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e  ** which contain
20f30 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  s the database. 
20f40 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67  ^If the path beg
20f50 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63  ins with a '/' c
20f60 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68  haracter, .** th
20f70 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  en it is interpr
20f80 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c  eted as an absol
20f90 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68  ute path. ^If th
20fa0 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20  e path does not 
20fb0 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61  begin .** with a
20fc0 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68   '/' (meaning th
20fd0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  at the authority
20fe0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74   section is omit
20ff0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49  ted from the URI
21000 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61  ).** then the pa
21010 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  th is interprete
21020 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20  d as a relative 
21030 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69  path. .** ^On wi
21040 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
21050 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
21060 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
21070 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
21080 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
21090 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b  . "C:")..**.** [
210a0 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
210b0 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
210c0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
210d0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
210e0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
210f0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
21100 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
21110 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
21120 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
21130 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
21140 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
21150 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  ** SQLite interp
21160 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69  rets the followi
21170 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70  ng three query p
21180 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a  arameters:.**.**
21190 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
211a0 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65  <b>vfs</b>: ^The
211b0 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72   "vfs" parameter
211c0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20   may be used to 
211d0 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65  specify the name
211e0 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53   of.**     a VFS
211f0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f   object that pro
21200 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74  vides the operat
21210 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
21220 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64  face that should
21230 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20  .**     be used 
21240 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
21250 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64  tabase file on d
21260 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70  isk. ^If this op
21270 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a  tion is set to.*
21280 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73  *     an empty s
21290 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c  tring the defaul
212a0 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20  t VFS object is 
212b0 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e  used. ^Specifyin
212c0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20  g an unknown.** 
212d0 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72      VFS is an er
212e0 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  ror. ^If sqlite3
212f0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
21300 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f  ed and the vfs o
21310 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
21320 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68  present, then th
21330 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
21340 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61  by the option ta
21350 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f  kes precedence o
21360 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76  ver.**     the v
21370 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
21380 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
21390 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
213a0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
213b0 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f    <li> <b>mode</
213c0 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70  b>: ^(The mode p
213d0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
213e0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72  set to either "r
213f0 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20  o", "rw",.**    
21400 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f   "rwc", or "memo
21410 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20  ry". Attempting 
21420 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79  to set it to any
21430 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a   other value is.
21440 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29  **     an error)
21450 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
21460 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
21470 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21480 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
21490 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
214a0 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
214b0 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
214c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
214d0 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
214e0 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
214f0 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
21500 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
21510 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  n_v2(). ^If the 
21520 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
21530 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
21540 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
21550 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21560 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
21570 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
21580 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
21590 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
215a0 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
215b0 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
215c0 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
215d0 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
215e0 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
215f0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
21600 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
21610 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
21620 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
21630 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
21640 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
21650 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73  tion is.**     s
21660 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74  et to "memory" t
21670 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d  hen a pure [in-m
21680 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20  emory database] 
21690 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73  that never reads
216a0 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65  .**     or write
216b0 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75  s from disk is u
216c0 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65  sed. ^It is an e
216d0 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20  rror to specify 
216e0 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20  a value for.**  
216f0 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61     the mode para
21700 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65  meter that is le
21710 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
21720 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
21730 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65  ed by.**     the
21740 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e   flags passed in
21750 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
21760 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21770 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21780 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65     <li> <b>cache
21790 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65  </b>: ^The cache
217a0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
217b0 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
217c0 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20  "shared" or.**  
217d0 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53     "private". ^S
217e0 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68  etting it to "sh
217f0 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c  ared" is equival
21800 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
21810 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  he.**     SQLITE
21820 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21830 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61  E bit in the fla
21840 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  gs argument pass
21850 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c  ed to.**     sql
21860 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
21870 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63  ^Setting the cac
21880 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
21890 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a  "private" is .**
218a0 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20       equivalent 
218b0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53  to setting the S
218c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
218d0 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20  TECACHE bit..** 
218e0 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f      ^If sqlite3_
218f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
21900 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65  d and the "cache
21910 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  " parameter is p
21920 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20  resent in.**    
21930 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c   a URI filename,
21940 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72   its value overr
21950 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f  ides any behavio
21960 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
21970 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
21980 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
21990 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
219a0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
219b0 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
219c0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
219d0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
219e0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
219f0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
21a00 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
21a10 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
21a20 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
21a30 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
21a40 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
21a50 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
21a60 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
21a70 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
21a80 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
21a90 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
21aa0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
21ab0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
21ac0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
21ad0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
21ae0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
21af0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
21b00 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
21b10 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
21b20 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
21b30 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
21b40 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
21b50 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
21b60 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
21b70 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21b80 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
21b90 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
21ba0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
21bb0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
21bc0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21bd0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
21be0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21bf0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
21c00 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
21c10 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
21c20 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
21c30 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
21c40 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21c50 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
21c60 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
21c70 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
21c80 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21c90 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
21ca0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
21cb0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
21cc0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
21cd0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
21ce0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
21cf0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
21d00 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
21d10 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
21d20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
21d30 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
21d40 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
21d50 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
21d60 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
21d70 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
21d80 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21d90 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
21da0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
21db0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
21dc0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
21dd0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
21de0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
21df0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
21e00 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
21e10 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
21e20 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
21e30 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
21e40 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
21e50 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
21e60 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
21e70 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
21e80 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
21e90 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21ea0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21eb0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21ec0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
21ed0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
21ee0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
21ef0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
21f00 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
21f10 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
21f20 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
21f30 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
21f40 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
21f50 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21f60 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21f70 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
21f80 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
21f90 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
21fa0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21fb0 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
21fc0 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
21fd0 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
21fe0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
21ff0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
22000 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
22010 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
22020 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
22030 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
22040 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
22050 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
22060 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
22070 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22080 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
22090 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
220a0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
220b0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
220c0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
220d0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
220e0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
220f0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
22100 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
22110 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
22120 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
22130 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
22140 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
22150 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
22160 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
22170 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
22180 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
22190 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
221a0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
221b0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
221c0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
221d0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
221e0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
221f0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
22200 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
22210 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
22220 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
22230 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
22240 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
22250 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
22260 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
22270 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
22280 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
22290 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
222a0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
222b0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
222c0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
222d0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
222e0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
222f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
22300 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
22310 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
22320 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
22330 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
22340 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
22350 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
22360 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
22370 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
22380 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
22390 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
223a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
223b0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
223c0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
223d0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
223e0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
223f0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
22400 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
22410 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
22420 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
22430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
22440 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
22450 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
22460 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
22470 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
22480 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
22490 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
224a0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
224b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
224c0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
224d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
224e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
224f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
22500 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
22510 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
22520 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
22530 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
22540 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
22550 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
22560 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
22570 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
22580 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
22590 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
225a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
225b0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
225c0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
225d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
225e0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
225f0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
22600 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
22610 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
22620 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
22630 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
22640 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
22650 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
22660 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
22670 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
22680 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
22690 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
226a0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
226b0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
226c0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
226d0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
226e0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
226f0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
22700 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
22710 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
22720 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
22730 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
22740 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
22750 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
22760 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
22770 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
22780 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
22790 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
227a0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
227b0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
227c0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
227d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
227e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
227f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
22800 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22810 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
22820 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
22830 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
22840 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
22850 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
22860 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
22870 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
22880 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
22890 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
228a0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
228b0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
228c0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
228d0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
228e0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
228f0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
22900 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
22910 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
22920 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
22930 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
22940 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
22950 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
22960 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
22970 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
22980 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22990 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
229a0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
229b0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
229c0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
229d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
229e0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
229f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
22a00 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
22a10 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
22a20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
22a30 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
22a40 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
22a50 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
22a60 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
22a70 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
22a80 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
22a90 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
22aa0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
22ab0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
22ac0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22ad0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
22ae0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
22af0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
22b00 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
22b10 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
22b20 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
22b30 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
22b40 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
22b50 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
22b60 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
22b70 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
22b80 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22b90 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
22ba0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
22bb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
22bc0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22bd0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
22be0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
22bf0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
22c00 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
22c10 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
22c20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
22c30 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
22c40 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
22c50 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
22c60 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
22c70 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
22c80 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
22c90 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
22ca0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
22cb0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
22cc0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
22cd0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
22ce0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
22cf0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
22d00 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
22d10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
22d20 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
22d30 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
22d40 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
22d50 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
22d60 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
22d70 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
22d80 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
22d90 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
22da0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22db0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
22dc0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
22dd0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
22de0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
22df0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
22e00 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
22e10 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
22e20 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
22e30 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
22e40 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
22e50 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
22e60 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
22e70 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
22e80 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
22e90 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
22ea0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
22eb0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
22ec0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
22ed0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
22ee0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
22ef0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
22f00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22f10 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
22f20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
22f30 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
22f40 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
22f50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22f60 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
22f70 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
22f80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22f90 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
22fa0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  t);.SQLITE_API s
22fb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
22fc0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
22fd0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
22fe0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
22ff0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
23000 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
23010 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
23020 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
23030 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
23040 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23050 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
23060 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
23070 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
23080 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
23090 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
230a0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
230b0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
230c0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
230d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
230e0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
230f0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
23100 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
23110 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
23120 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
23130 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
23140 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
23150 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
23160 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
23170 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
23180 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
23190 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
231a0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
231b0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
231c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
231d0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
231e0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
231f0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
23200 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
23210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
23220 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
23230 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
23240 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
23250 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
23260 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
23270 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
23280 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
23290 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
232a0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
232b0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
232c0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
232d0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
232e0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
232f0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
23300 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
23310 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
23320 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
23330 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
23340 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
23350 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
23360 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
23370 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
23380 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
23390 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
233a0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
233b0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
233c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
233d0 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
233e0 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
233f0 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
23400 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
23410 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
23420 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
23430 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
23440 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
23450 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
23460 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
23470 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
23480 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
23490 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
234a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
234b0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
234c0 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
234d0 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
234e0 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
234f0 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
23500 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
23510 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
23520 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
23530 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
23540 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
23550 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
23560 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
23570 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
23580 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
23590 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
235a0 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
235b0 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
235c0 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
235d0 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
235e0 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
235f0 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
23600 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
23610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23620 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
23630 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
23640 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
23650 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
23660 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
23670 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
23680 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
23690 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
236a0 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
236b0 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
236c0 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
236d0 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
236e0 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
236f0 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
23700 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
23710 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
23720 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
23730 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
23740 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
23750 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
23760 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
23770 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
23780 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
23790 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
237a0 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
237b0 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54  be set..*/.SQLIT
237c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
237d0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
237e0 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
237f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
23800 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
23810 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51  sqlite3 *db);.SQ
23820 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
23830 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
23840 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
23850 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
23860 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
23870 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
23880 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
23890 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
238a0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
238b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
238c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
238d0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
238e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
238f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
23900 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
23910 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
23920 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
23930 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
23940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
23950 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
23960 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
23970 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
23980 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
23990 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
239a0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
239b0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
239c0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
239d0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
239e0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
239f0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
23a00 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
23a10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
23a20 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
23a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
23a40 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
23a50 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
23a60 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
23a70 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
23a80 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
23a90 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
23aa0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
23ab0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
23ac0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
23ad0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
23ae0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23af0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
23b00 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
23b10 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
23b20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
23b30 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
23b40 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
23b50 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
23b60 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
23b70 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
23b80 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
23b90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
23ba0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
23bb0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
23bc0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
23bd0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
23be0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
23bf0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
23c00 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c10 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
23c20 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
23c30 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
23c40 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
23c50 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
23c60 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
23c70 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
23c80 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
23c90 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
23ca0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
23cb0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
23cc0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
23cd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
23ce0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
23cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23d00 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
23d10 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
23d20 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
23d30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
23d40 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
23d50 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
23d60 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
23d70 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
23d80 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
23d90 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
23da0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23db0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
23dc0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
23dd0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
23de0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
23df0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
23e00 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
23e10 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
23e20 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
23e30 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
23e40 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
23e50 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
23e60 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
23e70 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
23e80 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
23e90 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
23ea0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
23eb0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
23ec0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
23ed0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
23ee0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
23ef0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
23f00 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
23f10 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
23f20 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
23f30 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
23f40 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
23f50 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
23f60 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
23f70 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
23f80 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
23f90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
23fa0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
23fb0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
23fc0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
23fd0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
23fe0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23ff0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
24000 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
24010 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
24020 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
24030 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
24040 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
24050 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
24060 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
24070 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
24080 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
24090 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
240a0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
240b0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
240c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
240d0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
240e0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
240f0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
24100 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
24110 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
24120 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
24130 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
24140 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
24150 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
24160 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
24170 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
24180 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
24190 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
241a0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
241b0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
241c0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
241d0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
241e0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
241f0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
24200 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
24210 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
24220 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
24230 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
24240 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
24250 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
24260 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
24270 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
24280 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
24290 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
242a0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
242b0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
242c0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
242d0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
242e0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
242f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
24300 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
24310 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
24320 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
24330 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
24340 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
24350 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
24360 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
24370 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
24380 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
24390 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
243a0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
243b0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
243c0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
243d0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
243e0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
243f0 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
24400 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
24410 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
24420 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
24430 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
24440 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
24450 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
24460 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
24470 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
24480 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
24490 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
244a0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
244b0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
244c0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
244d0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
244e0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
244f0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
24500 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
24510 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
24520 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
24530 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
24540 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
24550 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24560 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
24570 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
24580 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
24590 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
245a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
245b0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
245c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
245d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
245e0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
245f0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
24600 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
24610 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
24620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24630 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
24640 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
24650 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
24660 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24670 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
24680 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
24690 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
246a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
246b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
246c0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
246d0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
246e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
246f0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24700 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
24710 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
24720 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
24730 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
24740 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
24750 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
24760 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
24770 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
24780 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
24790 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
247a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
247b0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
247c0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
247d0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
247e0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
247f0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
24800 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
24810 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
24820 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
24830 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24840 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
24850 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
24860 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
24870 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
24880 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24890 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
248a0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
248b0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
248c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
248d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
248e0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
248f0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
24900 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24910 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24920 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
24930 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
24940 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
24950 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
24960 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24970 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
24980 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
24990 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
249a0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
249b0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
249c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
249d0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
249e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
249f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24a00 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
24a10 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
24a20 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
24a30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24a40 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
24a50 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
24a60 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
24a70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
24a80 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
24a90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24aa0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
24ab0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
24ac0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
24ad0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
24ae0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
24af0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24b00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
24b10 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
24b20 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
24b30 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
24b40 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
24b50 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
24b60 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
24b70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24b80 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
24b90 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
24ba0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24bb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
24bc0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
24bd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24be0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24bf0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
24c00 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
24c10 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
24c20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
24c30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
24c40 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24c50 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
24c60 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
24c70 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24c80 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
24c90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24ca0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
24cb0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
24cc0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
24cd0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
24ce0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24d00 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
24d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
24d20 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
24d30 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
24d40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24d50 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
24d60 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
24d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
24d80 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
24d90 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
24da0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
24db0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
24dc0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
24dd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
24de0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
24df0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
24e00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24e10 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
24e20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
24e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24e40 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
24e50 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
24e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24e70 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24e80 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
24e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24ea0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24eb0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
24ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24ed0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
24ee0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
24ef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24f00 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
24f10 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
24f20 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
24f30 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
24f40 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
24f50 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
24f60 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
24f70 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
24f80 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
24f90 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
24fa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
24fb0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
24fc0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
24fd0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
24fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
24ff0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
25000 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
25010 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
25020 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
25030 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
25040 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
25050 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
25060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25070 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
25080 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
25090 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
250a0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
250b0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
250c0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
250d0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
250e0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
250f0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
25100 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
25110 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
25120 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
25130 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
25140 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
25150 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
25160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25170 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
25180 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
25190 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
251a0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
251b0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
251c0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
251d0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
251e0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
251f0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
25200 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
25210 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
25220 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
25230 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
25240 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
25250 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
25260 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
25270 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
25280 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
25290 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
252a0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
252b0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
252c0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
252d0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
252e0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
252f0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
25300 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
25310 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
25320 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
25330 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
25340 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
25350 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
25360 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
25370 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
25380 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
25390 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
253a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
253b0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
253c0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
253d0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
253e0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
253f0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
25400 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
25410 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
25420 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
25430 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
25440 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
25450 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
25460 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
25470 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
25480 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
25490 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
254a0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
254b0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
254c0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
254d0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
254e0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
254f0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
25500 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
25510 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
25520 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
25530 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
25540 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
25550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25560 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
25570 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
25580 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
25590 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
255a0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
255b0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
255c0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
255d0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
255e0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
255f0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
25600 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
25610 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
25620 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
25630 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
25640 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
25650 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
25660 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
25670 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
25680 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
25690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
256a0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
256b0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
256c0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
256d0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
256e0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
256f0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
25700 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
25710 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
25720 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
25730 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
25740 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
25750 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
25760 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
25770 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
25780 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25790 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
257a0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
257b0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
257c0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
257d0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
257e0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
257f0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
25800 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
25810 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
25820 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
25830 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
25840 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
25850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
25860 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
25870 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
25880 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
25890 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
258a0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
258b0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
258c0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
258d0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
258e0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
258f0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
25900 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
25910 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
25920 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
25930 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
25940 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
25950 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
25960 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
25970 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
25980 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
25990 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
259a0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
259b0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
259c0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
259d0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
259e0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
259f0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
25a00 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
25a10 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
25a20 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
25a30 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
25a40 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
25a50 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
25a60 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
25a70 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
25a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25a90 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
25aa0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
25ab0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
25ac0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
25ad0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
25ae0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
25af0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
25b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25b10 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
25b20 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
25b30 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
25b40 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
25b50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
25b60 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
25b70 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
25b80 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
25b90 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
25ba0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
25bb0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
25bc0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
25bd0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
25be0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
25bf0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
25c00 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
25c10 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25c20 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
25c30 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
25c40 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
25c50 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
25c60 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
25c70 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
25c80 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
25c90 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
25ca0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
25cb0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
25cc0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
25cd0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
25ce0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
25cf0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
25d00 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
25d10 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
25d20 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
25d30 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
25d40 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
25d50 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
25d60 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
25d70 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
25d80 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
25d90 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
25da0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
25db0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
25dc0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
25dd0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
25de0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
25df0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
25e00 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
25e10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
25e20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
25e30 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
25e40 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
25e50 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
25e60 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
25e70 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
25e80 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
25e90 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
25ea0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
25eb0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
25ec0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
25ed0 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
25ee0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
25ef0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25f00 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
25f10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25f20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
25f30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25f40 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
25f50 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25f60 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
25f70 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
25f80 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
25f90 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25fa0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25fb0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25fc0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25fd0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25fe0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25ff0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
26000 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26010 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26020 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26030 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
26040 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26050 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
26060 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26070 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26080 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
26090 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
260a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
260b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
260c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
260d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
260e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
260f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26100 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26110 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26120 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26130 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
26150 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26160 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26170 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
26180 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
26190 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
261a0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
261b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
261c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
261d0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
261e0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
261f0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26200 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
26210 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26220 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26230 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26240 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26250 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26260 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26270 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26280 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26290 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
262a0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
262b0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
262c0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
262d0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
262e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
262f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
26300 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
26310 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
26320 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
26330 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
26340 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
26350 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
26360 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
26370 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26380 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26390 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
263a0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
263b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
263c0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
263d0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
263e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
263f0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
26400 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26410 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26420 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
26430 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26440 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
26450 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
26460 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
26470 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
26480 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
26490 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
264a0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
264b0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
264c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
264d0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
264e0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
264f0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
26500 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
26510 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
26520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26530 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
26540 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
26550 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
26560 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
26570 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
26580 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
26590 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
265a0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
265b0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
265c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
265d0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
265e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
265f0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
26600 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
26610 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26620 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
26630 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
26640 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
26650 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
26660 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
26670 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
26680 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26690 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
266a0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
266b0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
266c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
266d0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
266e0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
266f0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
26700 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
26710 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
26720 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
26730 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
26740 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
26750 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
26760 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
26770 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
26780 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26790 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
267a0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
267b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
267c0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
267d0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
267e0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
267f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
26800 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
26810 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
26820 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
26830 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
26840 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
26850 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
26860 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26870 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
26880 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
26890 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
268a0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
268b0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
268c0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
268d0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
268e0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
268f0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
26900 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26910 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
26920 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
26930 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
26940 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
26950 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
26960 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
26970 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
26980 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
26990 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
269a0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
269b0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
269c0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
269d0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
269e0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
269f0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
26a00 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26a10 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
26a20 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
26a30 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
26a40 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
26a50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
26a60 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
26a70 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
26a80 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
26a90 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
26aa0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
26ab0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
26ac0 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
26ad0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
26ae0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
26af0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26b10 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
26b20 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26b30 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
26b40 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
26b50 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
26b60 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
26b70 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
26b80 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
26b90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ba0 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
26bb0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
26bc0 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
26bd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26be0 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
26bf0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
26c00 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
26c10 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
26c20 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26c30 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
26c40 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26c50 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
26c60 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
26c70 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
26c80 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
26c90 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
26ca0 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
26cb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
26cc0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
26cd0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
26ce0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
26cf0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
26d00 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
26d10 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
26d20 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
26d30 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
26d40 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
26d50 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
26d60 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
26d70 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
26d80 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
26d90 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
26da0 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
26db0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
26dc0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
26dd0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
26de0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
26df0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
26e00 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
26e10 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
26e20 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
26e30 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
26e40 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
26e50 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
26e60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26e70 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
26e80 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
26e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
26ea0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
26eb0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
26ec0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
26ed0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26ee0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
26ef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
26f00 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
26f10 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
26f20 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
26f30 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
26f40 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
26f50 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
26f60 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
26f70 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
26f80 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
26f90 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
26fa0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
26fb0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
26fc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
26fd0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
26fe0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
26ff0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
27000 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
27010 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
27020 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27030 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
27040 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
27050 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
27060 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
27070 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
27080 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27090 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
270a0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
270b0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
270c0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
270d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
270e0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
270f0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
27100 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
27110 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
27120 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
27130 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
27140 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
27150 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27160 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
27170 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
27180 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
27190 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
271a0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
271b0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
271c0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
271d0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
271e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
271f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27200 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
27210 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
27220 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27230 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
27240 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
27250 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
27260 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
27270 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
27280 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
27290 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
272a0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
272b0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
272c0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
272d0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
272e0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
272f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
27300 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
27310 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
27320 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
27330 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
27340 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
27350 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
27360 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
27370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
27380 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
27390 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
273a0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
273b0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
273c0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
273d0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
273e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
273f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
27400 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
27410 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
27420 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
27430 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
27440 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27450 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
27460 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
27470 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
27480 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27490 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
274a0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
274b0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
274c0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
274d0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
274e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
274f0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
27500 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
27510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27520 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
27530 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
27540 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
27550 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
27560 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
27570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27580 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
27590 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
275a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
275b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
275c0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
275d0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
275e0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
275f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
27600 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
27610 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
27620 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
27630 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27640 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
27650 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
27660 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
27670 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
27680 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
27690 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
276a0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
276b0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
276c0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
276d0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
276e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
276f0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
27700 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
27710 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
27720 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
27730 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
27740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27750 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27760 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
27770 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27780 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
27790 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
277a0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
277b0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
277c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
277d0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
277e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
277f0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
27800 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27810 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
27820 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
27830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
27840 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
27850 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
27860 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
27870 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
27880 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
27890 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
278a0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
278b0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
278c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
278d0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
278e0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
278f0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
27900 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
27910 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
27920 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
27930 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
27940 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
27950 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
27960 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
27970 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
27980 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
27990 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
279a0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
279b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
279c0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
279d0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
279e0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
279f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
27a00 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
27a10 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
27a20 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
27a30 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
27a40 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
27a50 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
27a60 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
27a70 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
27a80 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
27a90 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
27aa0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
27ab0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
27ac0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
27ad0 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
27ae0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
27af0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
27b00 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
27b10 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
27b20 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
27b30 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
27b40 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
27b50 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
27b60 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
27b70 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
27b80 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
27b90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27ba0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
27bb0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27bc0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
27bd0 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
27be0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
27bf0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
27c00 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
27c10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
27c20 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
27c30 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
27c40 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
27c50 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
27c60 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
27c70 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
27c80 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
27c90 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
27ca0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
27cb0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
27cc0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
27cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
27ce0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
27cf0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
27d00 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
27d10 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
27d20 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
27d30 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
27d40 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
27d50 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
27d60 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
27d70 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
27d80 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
27d90 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
27da0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
27db0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
27dc0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
27dd0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
27de0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
27df0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
27e00 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
27e10 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
27e20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
27e30 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
27e40 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27e50 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
27e60 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
27e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
27e80 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
27e90 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
27ea0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
27eb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
27ec0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
27ed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27ee0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
27ef0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
27f00 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
27f10 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
27f20 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
27f30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27f40 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
27f50 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
27f60 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
27f70 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
27f80 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
27f90 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
27fa0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
27fb0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
27fc0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
27fd0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
27fe0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
27ff0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
28000 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
28010 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28020 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
28030 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
28040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
28050 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
28060 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
28070 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28080 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
28090 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
280a0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
280b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
280c0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
280d0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
280e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
280f0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
28100 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
28110 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
28120 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28140 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
28150 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
28160 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
28170 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
28180 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
28190 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
281a0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
281b0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
281c0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
281d0 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
281e0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
281f0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
28200 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
28210 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
28220 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
28230 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
28240 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
28250 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
28260 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
28270 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
28280 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
28290 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
282a0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
282b0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
282c0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
282d0 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
282e0 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
282f0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
28300 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
28310 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
28320 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
28330 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
28340 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
28350 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
28360 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
28370 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
28380 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
28390 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
283a0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
283b0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
283c0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
283d0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
283e0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
283f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
28400 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
28410 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
28420 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
28430 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
28440 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
28450 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
28460 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
28470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28480 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
28490 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
284a0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
284b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
284c0 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
284d0 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
284e0 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
284f0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
28500 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
28510 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
28520 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
28530 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
28540 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
28550 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
28560 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
28570 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
28580 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
28590 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
285a0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
285b0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
285c0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
285d0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
285e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
285f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28610 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
28620 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
28630 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
28640 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
28650 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
28660 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
28670 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
28680 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
28690 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
286a0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
286b0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
286c0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
286d0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
286e0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
286f0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
28700 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
28710 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
28720 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
28730 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
28740 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
28750 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
28760 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
28770 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
28780 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
28790 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
287a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
287b0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
287c0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
287d0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
287e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
287f0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
28800 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
28810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28820 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
28830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28840 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
28850 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
28860 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
28870 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
28880 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28890 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
288a0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
288b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
288c0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
288d0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
288e0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
288f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28900 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
28910 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
28920 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
28930 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
28940 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
28950 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
28960 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
28970 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
28980 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
28990 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
289a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
289b0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
289c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
289d0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
289e0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
289f0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
28a00 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
28a10 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
28a20 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
28a30 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
28a40 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
28a50 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
28a60 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
28a70 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
28a80 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
28a90 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
28aa0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
28ab0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28ac0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28ad0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
28ae0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28af0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
28b00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
28b10 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28b20 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
28b30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28b40 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
28b50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28b60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
28b70 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28b80 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
28b90 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28ba0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
28bb0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
28bc0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
28bd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28be0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
28bf0 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
28c00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28c10 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
28c20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28c30 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
28c40 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
28c50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28c60 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
28c70 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
28c80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28c90 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
28ca0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28cb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
28cc0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28cd0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
28ce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28cf0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
28d00 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28d10 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
28d20 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
28d30 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28d40 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
28d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28d60 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
28d70 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
28d80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28d90 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
28da0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28db0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
28dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
28dd0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
28de0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
28df0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
28e00 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
28e10 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
28e20 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
28e30 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
28e40 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
28e50 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
28e60 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
28e70 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
28e80 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
28e90 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
28ea0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
28eb0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
28ec0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
28ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28ee0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
28ef0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
28f00 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
28f10 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
28f20 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
28f30 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
28f40 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
28f50 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
28f60 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
28f70 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
28f80 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
28f90 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
28fa0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
28fb0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
28fc0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
28fd0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
28fe0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
28ff0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
29000 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
29010 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29020 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29030 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29040 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29050 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
29060 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
29070 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29080 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
290a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
290b0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
290c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
290d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
290e0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
290f0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
29100 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29110 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
29120 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
29130 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
29140 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
29150 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
29160 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29170 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
29180 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
29190 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
291a0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
291b0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
291c0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
291d0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
291e0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
291f0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
29200 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
29210 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
29220 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
29230 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
29240 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
29250 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
29260 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
29270 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
29280 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
29290 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
292a0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
292b0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
292c0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
292d0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
292e0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
292f0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
29300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29310 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
29320 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
29330 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
29340 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
29350 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
29360 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
29370 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
29380 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
29390 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
293a0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
293b0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
293c0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
293d0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
293e0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
293f0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
29400 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
29410 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
29420 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29430 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
29440 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
29450 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29460 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29470 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29480 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29490 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
294a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
294b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
294c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
294d0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
294e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
294f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29500 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
29510 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
29520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
29530 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
29540 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
29550 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
29560 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
29570 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
29580 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
29590 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
295a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
295b0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
295c0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
295d0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
295e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
295f0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
29600 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
29610 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
29620 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
29630 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
29640 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
29650 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
29660 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
29670 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
29680 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
29690 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
296a0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
296b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
296c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
296d0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
296e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
296f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
29700 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29710 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
29720 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
29730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29740 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
29750 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
29760 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29770 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29790 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
297a0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
297b0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
297c0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
297d0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
297e0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
297f0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
29800 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
29810 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
29820 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
29830 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29840 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
29850 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
29860 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
29870 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
29880 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
29890 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
298a0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
298b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
298c0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
298d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
298e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
298f0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
29900 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
29910 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
29920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
29930 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
29940 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
29950 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
29960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29970 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
29980 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
29990 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
299a0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
299b0 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
299c0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
299d0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
299e0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
299f0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
29a00 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
29a10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29a20 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
29a30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29a50 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
29a60 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
29a70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
29a80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29a90 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
29aa0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
29ab0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
29ac0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
29ad0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29ae0 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
29af0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
29b00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
29b10 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
29b20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
29b30 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
29b40 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
29b50 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29b60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29b70 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
29b80 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
29b90 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
29ba0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29bb0 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
29bc0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
29bd0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
29be0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
29bf0 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
29c00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
29c10 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
29c20 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
29c30 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
29c40 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
29c50 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29c60 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
29c70 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
29c80 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29c90 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
29ca0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
29cb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29cc0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
29cd0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
29ce0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
29cf0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
29d00 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
29d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
29d20 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
29d30 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
29d40 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
29d50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29d60 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
29d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29d80 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
29d90 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
29da0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
29db0 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
29dc0 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
29dd0 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
29de0 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
29df0 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
29e00 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
29e10 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
29e20 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
29e30 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
29e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
29e50 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
29e60 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
29e70 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
29e80 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
29e90 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
29ea0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
29eb0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
29ec0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
29ed0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
29ee0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
29ef0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
29f00 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
29f10 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
29f20 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
29f30 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
29f40 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
29f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29f60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29f70 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
29f80 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
29f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29fa0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
29fb0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
29fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
29fd0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
29fe0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
29ff0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2a000 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2a010 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2a020 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2a030 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2a040 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2a050 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2a060 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2a070 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2a080 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2a090 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2a0a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2a0b0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2a0c0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2a0d0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2a0e0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2a0f0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2a100 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2a110 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2a120 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2a130 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2a140 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2a150 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2a160 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2a170 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2a180 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2a190 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2a1a0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2a1b0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2a1c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a1d0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2a1e0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2a1f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2a200 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2a210 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2a220 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2a230 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2a240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a250 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2a260 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2a270 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2a280 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2a290 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2a2a0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2a2b0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2a2c0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2a2d0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2a2e0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2a2f0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2a300 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2a310 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2a320 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2a330 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2a340 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2a350 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2a360 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2a370 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2a380 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2a390 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2a3a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2a3b0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2a3c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2a3d0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2a3e0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2a3f0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2a400 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2a410 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2a420 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2a430 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2a440 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2a450 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2a460 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2a470 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2a480 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2a490 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2a4a0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2a4b0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2a4c0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2a4d0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2a4e0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2a4f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2a500 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2a510 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2a520 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2a530 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2a540 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2a550 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2a560 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2a570 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2a580 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2a590 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2a5a0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2a5b0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2a5c0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2a5d0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2a5e0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2a5f0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2a600 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2a610 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2a620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2a630 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2a640 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2a650 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2a660 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2a670 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2a680 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2a690 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2a6a0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2a6b0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2a6c0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2a6d0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2a6e0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2a6f0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2a700 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2a710 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2a720 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2a730 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2a740 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2a750 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2a760 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2a770 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2a780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2a790 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2a7a0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2a7b0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2a7c0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2a7d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2a7e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2a7f0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2a800 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2a810 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a820 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2a830 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2a840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2a850 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2a860 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2a870 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2a880 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a890 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2a8a0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a8b0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2a8c0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2a8d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2a8e0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2a8f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2a900 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2a910 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a920 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
2a930 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2a940 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2a950 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a960 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2a970 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2a980 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2a990 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2a9a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a9b0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2a9c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a9d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a9e0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2a9f0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2aa00 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2aa10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2aa20 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2aa30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2aa40 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2aa50 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2aa60 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2aa70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2aa80 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2aa90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2aaa0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2aab0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2aac0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2aad0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2aae0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2aaf0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2ab00 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2ab10 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2ab20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2ab30 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ab40 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2ab50 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2ab60 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2ab70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2ab80 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2ab90 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2aba0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2abb0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2abc0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2abd0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2abe0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2abf0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2ac00 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2ac10 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2ac20 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2ac30 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2ac40 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2ac50 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2ac60 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2ac70 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2ac80 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2ac90 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2aca0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2acb0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2acc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2acd0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2ace0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2acf0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2ad00 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2ad10 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2ad20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2ad30 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2ad40 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2ad50 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2ad60 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2ad70 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2ad80 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2ad90 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2ada0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2adb0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2adc0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2add0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2ade0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2adf0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2ae00 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2ae10 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2ae20 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2ae30 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2ae40 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2ae50 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2ae60 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2ae70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ae80 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2ae90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2aea0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2aeb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2aec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2aed0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2aee0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2aef0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2af00 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2af10 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2af20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2af30 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2af40 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2af50 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2af60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2af70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2af80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2af90 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2afa0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2afb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2afc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2afd0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2afe0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2aff0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2b000 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2b010 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2b020 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2b030 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2b040 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2b050 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2b060 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2b070 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2b080 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2b090 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2b0a0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2b0b0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2b0c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b0d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2b0e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2b0f0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2b100 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2b110 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2b120 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2b130 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2b140 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2b150 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2b160 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2b170 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2b180 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2b190 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2b1a0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2b1b0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2b1c0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2b1d0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2b1e0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2b1f0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2b200 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2b210 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2b220 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2b230 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2b240 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2b250 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2b260 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2b270 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2b280 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2b290 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2b2a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2b2b0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2b2c0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2b2d0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2b2e0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2b2f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2b300 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2b310 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2b320 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2b330 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2b340 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2b350 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2b360 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2b370 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2b380 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2b390 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2b3a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2b3b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2b3c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2b3d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2b3e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2b3f0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2b400 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2b410 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2b420 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2b430 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2b440 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2b450 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2b460 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2b470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2b480 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2b490 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2b4a0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2b4b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2b4c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2b4d0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2b4e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2b4f0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2b500 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b510 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2b520 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2b530 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2b540 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2b550 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2b560 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2b570 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2b580 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2b590 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2b5a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2b5b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2b5c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2b5d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2b5e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2b5f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2b600 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2b610 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2b620 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2b630 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2b640 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2b650 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2b660 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2b670 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2b680 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2b690 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2b6a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2b6b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2b6c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2b6d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2b6e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2b6f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2b700 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2b710 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2b720 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2b730 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2b740 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2b750 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2b760 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2b770 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2b780 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2b790 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2b7a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2b7b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2b7c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2b7d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2b7e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2b7f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2b800 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b810 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2b820 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b830 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2b840 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2b850 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2b860 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2b870 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2b880 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2b890 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2b8a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2b8b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2b8c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2b8d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2b8e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2b8f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2b900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b910 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2b920 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2b930 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2b940 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2b950 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2b960 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2b970 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2b980 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2b990 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2b9a0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2b9b0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2b9c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b9d0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2b9e0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2b9f0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2ba00 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2ba10 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2ba20 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2ba30 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2ba40 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2ba50 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2ba60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ba70 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2ba80 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2ba90 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2baa0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2bab0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2bac0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2bad0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2bae0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2baf0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2bb00 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2bb10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2bb20 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2bb30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2bb40 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2bb50 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2bb60 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2bb70 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2bb80 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2bb90 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2bba0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2bbb0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2bbc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bbd0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2bbe0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2bbf0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2bc00 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2bc10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2bc20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2bc30 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2bc40 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2bc50 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2bc60 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2bc70 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2bc80 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2bc90 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2bca0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2bcb0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2bcc0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2bcd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2bce0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2bcf0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2bd00 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2bd10 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2bd20 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2bd30 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2bd40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2bd50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2bd60 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2bd70 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2bd80 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2bd90 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2bda0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2bdb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2bdc0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2bdd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2bde0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2bdf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2be00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2be10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2be20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2be30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2be40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2be50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2be60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2be70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2be80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2be90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2bea0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2beb0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2bec0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2bed0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2bee0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2bef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2bf00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2bf10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bf20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2bf30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2bf40 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2bf50 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2bf60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2bf70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2bf80 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2bf90 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2bfa0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2bfb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2bfc0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2bfd0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2bfe0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2bff0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2c000 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2c010 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
2c020 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c030 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2c040 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2c050 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2c060 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2c070 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
2c080 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2c090 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2c0a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2c0b0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2c0c0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2c0d0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2c0e0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2c0f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c100 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2c110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2c120 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2c130 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2c140 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2c150 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2c160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2c170 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2c180 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2c190 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2c1a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c1b0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2c1c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2c1d0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2c1e0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2c1f0 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2c200 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2c210 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2c220 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2c230 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2c240 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2c250 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2c260 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2c270 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2c280 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2c290 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2c2a0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2c2b0 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2c2c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c2d0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2c2e0 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2c2f0 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2c300 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2c310 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2c320 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2c330 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2c340 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2c350 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2c360 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2c370 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2c380 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2c390 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c3a0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2c3b0 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
2c3c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2c3d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c3e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2c3f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2c400 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2c410 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2c420 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2c430 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2c440 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2c450 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2c460 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2c470 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2c480 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2c490 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c4a0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2c4b0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2c4c0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2c4d0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2c4e0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2c4f0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2c500 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2c510 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2c520 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2c530 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2c540 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2c550 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2c560 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2c570 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2c580 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2c590 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2c5a0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2c5b0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2c5c0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2c5d0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2c5e0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2c5f0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2c600 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2c610 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2c620 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2c630 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2c640 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2c650 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2c660 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2c670 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2c680 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2c690 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2c6a0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2c6b0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2c6c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2c6d0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2c6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2c6f0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2c700 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2c710 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2c720 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2c730 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2c740 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2c750 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2c760 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2c770 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2c780 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2c790 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2c7a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2c7b0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2c7c0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2c7d0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2c7e0 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2c7f0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2c800 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2c810 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2c820 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c830 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2c840 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2c850 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2c860 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2c870 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2c880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c890 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2c8a0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2c8b0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2c8c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c8d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2c8e0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2c8f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2c900 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2c910 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2c920 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2c930 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2c940 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2c950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2c960 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2c970 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2c980 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2c990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2c9a0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2c9b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2c9c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2c9d0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2c9e0 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2c9f0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2ca00 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2ca10 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2ca20 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2ca30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ca40 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2ca50 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2ca60 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2ca70 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2ca80 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2ca90 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2caa0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2cab0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cac0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2cad0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2cae0 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2caf0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2cb00 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2cb10 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2cb20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2cb30 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2cb40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cb50 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2cb60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2cb70 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2cb80 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2cb90 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2cba0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2cbb0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2cbc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2cbd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2cbe0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2cbf0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2cc00 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2cc10 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2cc20 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2cc30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2cc40 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2cc50 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2cc60 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2cc70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2cc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cc90 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2cca0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2ccb0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2ccc0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2ccd0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2cce0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2ccf0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2cd00 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2cd10 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2cd20 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2cd30 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2cd40 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2cd50 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2cd60 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2cd70 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2cd80 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2cd90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2cda0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2cdb0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2cdc0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2cdd0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2cde0 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2cdf0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2ce00 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2ce10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2ce20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2ce30 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2ce40 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2ce50 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2ce60 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2ce70 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2ce80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ce90 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2cea0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2ceb0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2cec0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ced0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2cee0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2cef0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2cf00 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2cf10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2cf20 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2cf30 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2cf40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2cf50 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2cf60 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2cf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cf80 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2cf90 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2cfa0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2cfb0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2cfc0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2cfd0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2cfe0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2cff0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d000 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2d010 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2d020 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2d030 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2d040 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2d050 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2d060 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d070 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2d080 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d090 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2d0a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d0b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2d0c0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2d0d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d0e0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2d0f0 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2d100 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2d110 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2d120 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2d130 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d140 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2d150 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2d160 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d170 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2d180 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d190 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2d1a0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2d1b0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2d1c0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2d1d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d1e0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2d1f0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2d200 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2d210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d220 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2d230 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2d240 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2d250 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2d260 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2d270 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2d280 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d290 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2d2a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d2b0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2d2c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d2d0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2d2e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2d2f0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2d300 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2d310 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2d320 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2d330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d340 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2d350 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2d360 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2d370 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2d380 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2d390 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2d3a0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2d3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d3c0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2d3d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d3e0 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2d3f0 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2d400 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2d410 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2d420 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2d430 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2d440 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2d450 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2d460 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d470 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2d480 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2d490 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2d4a0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2d4b0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2d4c0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2d4d0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2d4e0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2d4f0 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2d500 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2d510 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2d520 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2d530 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2d540 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2d550 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d560 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2d570 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d580 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2d590 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2d5a0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2d5b0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2d5c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2d5d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2d5e0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2d5f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d600 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2d610 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2d620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2d630 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2d640 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2d650 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2d660 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2d670 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d680 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2d690 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2d6a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2d6b0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2d6c0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2d6d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2d6e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2d6f0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2d700 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2d710 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2d720 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2d730 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2d740 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2d750 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2d760 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2d770 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2d780 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2d790 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2d7a0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2d7b0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2d7c0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2d7d0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2d7e0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2d7f0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2d800 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2d810 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2d820 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2d830 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2d840 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2d850 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2d860 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2d870 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2d880 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2d890 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2d8a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2d8b0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2d8c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2d8d0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2d8e0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2d8f0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2d900 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d910 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2d920 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2d930 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2d940 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d950 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2d960 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2d970 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2d980 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2d990 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2d9a0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2d9b0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2d9c0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2d9d0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2d9e0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2d9f0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2da00 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2da10 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2da20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2da30 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2da40 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2da50 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2da60 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2da70 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2da80 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2da90 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2daa0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2dab0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2dac0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2dad0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2dae0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2daf0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2db00 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2db10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2db20 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2db30 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2db40 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2db50 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2db60 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2db70 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2db80 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2db90 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2dba0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2dbb0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2dbc0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2dbd0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2dbe0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2dbf0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2dc00 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2dc10 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2dc20 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2dc30 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2dc40 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2dc50 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2dc60 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2dc70 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2dc80 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2dc90 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2dca0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2dcb0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2dcc0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2dcd0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2dce0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2dcf0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2dd00 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2dd10 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2dd20 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2dd30 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2dd40 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2dd50 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2dd60 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2dd70 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2dd80 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2dd90 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2dda0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2ddb0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2ddc0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2ddd0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2dde0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2ddf0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2de00 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2de10 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2de20 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2de30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2de40 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2de50 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2de60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2de70 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2de80 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2de90 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2dea0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2deb0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2dec0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2ded0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2dee0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2def0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2df00 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2df10 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2df20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2df30 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2df40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2df50 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2df60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2df70 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2df80 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2df90 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2dfa0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2dfb0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2dfc0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2dfd0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2dfe0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2dff0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2e000 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2e010 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2e020 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2e030 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2e040 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2e050 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2e060 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2e070 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2e080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e090 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2e0a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e0b0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2e0c0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2e0d0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2e0e0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2e0f0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2e100 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2e110 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2e120 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2e130 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2e140 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2e150 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2e160 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2e170 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2e180 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2e190 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2e1a0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2e1b0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2e1c0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2e1d0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2e1e0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2e1f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2e200 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2e210 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2e220 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2e230 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2e240 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2e250 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2e260 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2e270 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2e280 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2e290 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2e2a0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2e2b0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2e2c0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2e2d0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2e2e0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2e2f0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2e300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e310 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2e320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e330 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2e340 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2e350 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2e360 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2e370 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2e380 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e3a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2e3b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e3c0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2e3d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2e3e0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2e3f0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2e400 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2e410 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e420 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2e430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e440 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2e450 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2e460 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2e470 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2e480 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2e490 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2e4a0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2e4b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2e4c0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2e4d0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2e4e0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2e4f0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2e500 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2e510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e520 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2e530 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2e540 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2e550 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2e560 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2e570 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2e580 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2e590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e5a0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2e5b0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2e5c0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2e5d0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2e5e0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2e5f0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2e600 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2e610 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e620 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2e630 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e640 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e650 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2e660 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2e670 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2e680 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2e690 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2e6a0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2e6b0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2e6c0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e6d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2e6e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2e6f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e700 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2e710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2e720 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2e730 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2e740 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2e750 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2e760 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2e770 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2e780 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2e790 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2e7a0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2e7b0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2e7c0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2e7d0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2e7e0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2e7f0 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2e800 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2e810 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2e820 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2e830 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2e840 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2e850 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2e860 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e870 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2e880 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e890 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2e8a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2e8b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2e8c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e8d0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2e8e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2e8f0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2e900 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e910 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2e920 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2e930 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2e940 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e950 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2e960 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2e970 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2e980 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e990 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2e9a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2e9b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2e9c0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e9d0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2e9e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2e9f0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2ea00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ea10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ea20 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2ea30 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ea40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ea50 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2ea60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ea70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ea80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ea90 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2eaa0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2eab0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2eac0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2ead0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2eae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2eaf0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2eb00 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2eb10 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2eb20 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2eb30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2eb40 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2eb50 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2eb60 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2eb70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2eb80 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2eb90 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2eba0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2ebb0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2ebc0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2ebd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ebe0 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2ebf0 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2ec00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2ec10 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2ec20 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2ec30 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2ec40 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2ec50 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2ec60 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2ec70 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2ec80 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2ec90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2eca0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2ecb0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2ecc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2ecd0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2ece0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2ecf0 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2ed00 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2ed10 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2ed20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2ed30 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2ed40 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2ed50 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2ed60 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2ed70 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ed80 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2ed90 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2eda0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2edb0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2edc0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2edd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2ede0 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2edf0 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2ee00 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2ee10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2ee20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ee30 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2ee40 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2ee50 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2ee60 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2ee70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ee80 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2ee90 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2eea0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2eeb0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2eec0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2eed0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2eee0 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2eef0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2ef00 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2ef10 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2ef20 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2ef30 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2ef40 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2ef50 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2ef60 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2ef70 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2ef80 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2ef90 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2efa0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2efb0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2efc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
2efd0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2efe0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2eff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2f000 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2f010 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2f020 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f030 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2f040 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2f050 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2f060 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2f070 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2f080 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2f090 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2f0a0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2f0b0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2f0c0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2f0d0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2f0e0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2f0f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2f100 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2f110 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2f120 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2f130 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2f140 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2f150 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2f160 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2f170 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2f180 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2f190 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2f1a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f1b0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2f1c0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2f1d0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2f1e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2f1f0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2f200 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f210 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2f220 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f230 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2f240 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2f250 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2f260 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2f270 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2f280 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2f290 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2f2a0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2f2b0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2f2c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2f2d0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2f2e0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2f2f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2f300 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2f310 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f320 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2f330 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2f340 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2f350 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2f360 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2f370 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2f380 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2f390 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2f3a0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2f3b0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2f3c0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2f3d0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2f3e0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2f3f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2f400 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f410 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2f420 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2f430 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2f440 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2f450 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2f460 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2f470 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2f480 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2f490 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2f4a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f4b0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f4c0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2f4d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f4e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f4f0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2f500 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2f510 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2f520 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2f530 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2f540 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2f550 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2f560 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2f570 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2f580 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2f590 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2f5a0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2f5b0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2f5c0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2f5d0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2f5e0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2f5f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2f600 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2f610 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2f620 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2f630 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2f640 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2f650 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2f660 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2f670 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2f680 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2f690 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2f6a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2f6b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2f6c0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2f6d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2f6e0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2f6f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2f700 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2f710 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2f720 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2f730 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2f740 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2f750 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f760 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2f770 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2f780 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2f790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2f7a0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2f7b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2f7c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2f7d0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2f7e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2f7f0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2f800 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2f810 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2f820 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2f830 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2f840 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2f850 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2f860 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2f870 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2f880 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2f890 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2f8a0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2f8b0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2f8c0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2f8d0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2f8e0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2f8f0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2f900 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2f910 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2f920 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2f930 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f940 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2f950 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2f960 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2f970 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2f980 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f990 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2f9a0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2f9b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2f9c0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2f9d0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2f9e0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2f9f0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2fa00 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2fa10 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2fa20 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2fa30 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2fa40 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2fa50 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2fa60 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2fa70 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2fa80 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2fa90 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2faa0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2fab0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2fac0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2fad0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2fae0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2faf0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2fb00 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2fb10 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2fb20 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2fb30 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2fb40 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2fb50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2fb60 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2fb70 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2fb80 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2fb90 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2fba0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2fbb0 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2fbc0 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2fbd0 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2fbe0 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2fbf0 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2fc00 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2fc10 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2fc20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2fc30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fc40 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2fc50 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2fc60 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2fc70 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2fc80 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2fc90 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2fca0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2fcb0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2fcc0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2fcd0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2fce0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2fcf0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2fd00 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2fd10 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2fd20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2fd30 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2fd40 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2fd50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2fd60 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2fd70 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2fd80 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2fd90 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2fda0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2fdb0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2fdc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2fdd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2fde0 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2fdf0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2fe00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2fe10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2fe20 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2fe30 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2fe40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2fe50 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2fe60 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2fe70 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2fe80 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2fe90 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2fea0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2feb0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2fec0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2fed0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2fee0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2fef0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2ff00 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2ff10 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2ff20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2ff30 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2ff40 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2ff50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2ff60 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2ff70 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2ff80 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2ff90 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2ffa0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2ffb0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2ffc0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2ffd0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2ffe0 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2fff0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
30000 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
30010 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
30020 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
30030 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
30040 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
30050 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
30060 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
30070 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
30080 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
30090 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
300a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
300b0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
300c0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
300d0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
300e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
300f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
30100 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
30110 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
30120 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
30130 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
30140 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
30150 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
30160 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
30170 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
30180 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
30190 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
301a0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
301b0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
301c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
301d0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
301e0 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
301f0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
30200 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
30210 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
30220 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
30230 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
30240 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
30250 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
30260 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
30270 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
30280 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
30290 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
302a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
302b0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
302c0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
302d0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
302e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
302f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
30300 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
30310 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30320 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
30330 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
30340 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
30350 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
30360 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
30370 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
30380 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
30390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
303a0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
303b0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
303c0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
303d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
303e0 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
303f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30400 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
30410 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
30420 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
30430 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
30440 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
30450 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
30460 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
30470 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
30480 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
30490 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
304a0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
304b0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
304c0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
304d0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
304e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
304f0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
30500 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
30510 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
30520 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
30530 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
30540 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
30550 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
30560 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
30570 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
30580 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
30590 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
305a0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
305b0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
305c0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
305d0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
305e0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
305f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30600 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
30610 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
30620 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30630 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
30640 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
30650 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
30660 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
30670 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
30680 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
30690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
306a0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
306b0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
306c0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
306d0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
306e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
306f0 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
30700 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
30710 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
30720 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
30730 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
30740 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
30750 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
30760 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
30770 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
30780 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
30790 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
307a0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
307b0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
307c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
307d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
307e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
307f0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
30800 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
30810 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
30820 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30830 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30840 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
30850 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
30860 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
30870 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
30880 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
30890 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
308a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
308b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
308c0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
308d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
308e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
308f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30900 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30910 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
30920 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30930 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30940 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
30950 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
30960 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
30970 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
30980 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
30990 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
309a0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
309b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
309c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
309d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
309e0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
309f0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30a00 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
30a10 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
30a20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
30a30 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
30a40 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
30a50 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
30a60 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
30a70 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
30a80 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
30a90 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
30aa0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
30ab0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
30ac0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
30ad0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
30ae0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
30af0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
30b00 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
30b10 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
30b20 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
30b30 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
30b40 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
30b50 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
30b60 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
30b70 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
30b80 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
30b90 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
30ba0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30bb0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
30bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30bd0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
30be0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
30bf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
30c00 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
30c10 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
30c20 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
30c30 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
30c40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30c50 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
30c60 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
30c70 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
30c80 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
30c90 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
30ca0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
30cb0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
30cc0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
30cd0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
30ce0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
30cf0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
30d00 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
30d10 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
30d20 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
30d30 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
30d40 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
30d50 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
30d60 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
30d70 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
30d80 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
30d90 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
30da0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
30db0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
30dd0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
30de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
30df0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
30e00 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30e10 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
30e20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
30e30 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
30e40 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30e50 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
30e60 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
30e70 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
30e80 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
30e90 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
30ea0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30eb0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
30ec0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
30ed0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
30ee0 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
30ef0 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
30f00 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
30f10 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
30f20 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30f30 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
30f40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
30f50 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
30f60 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30f70 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
30f80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
30f90 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
30fa0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
30fb0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
30fc0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
30fd0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
30fe0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30ff0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
31000 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
31010 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
31020 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
31030 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
31040 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
31050 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
31060 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
31070 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
31080 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
31090 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
310a0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
310b0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
310c0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
310d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
310e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
310f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31100 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
31110 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
31120 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
31130 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
31140 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
31150 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
31160 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
31170 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
31180 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
31190 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
311a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
311b0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
311c0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
311d0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
311e0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
311f0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
31200 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
31210 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
31220 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
31230 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
31240 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31250 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
31260 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
31270 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
31280 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31290 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
312a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
312b0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
312c0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
312d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
312e0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
312f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
31300 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
31310 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
31320 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
31330 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
31340 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
31350 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
31360 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
31370 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
31380 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
31390 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
313a0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
313b0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
313c0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
313d0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
313e0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
313f0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
31400 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
31410 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
31420 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
31430 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
31440 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
31450 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
31460 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
31470 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
31480 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
31490 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
314a0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
314b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
314c0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
314d0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
314e0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
314f0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
31500 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
31510 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
31520 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
31530 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
31540 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
31550 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
31560 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
31570 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
31580 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
31590 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
315a0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
315b0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
315c0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
315d0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
315e0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
315f0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
31600 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
31610 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
31620 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
31630 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
31640 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
31650 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
31660 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
31670 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
31680 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
31690 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
316a0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
316b0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
316c0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
316d0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
316e0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
316f0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
31700 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
31710 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
31720 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
31730 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
31740 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
31750 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
31760 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31770 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
31780 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
31790 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
317a0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
317b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
317c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
317d0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
317e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
317f0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
31800 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
31810 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
31820 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
31830 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
31840 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
31850 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
31860 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
31870 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
31880 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
31890 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
318a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
318b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
318c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
318d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
318e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
318f0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
31900 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
31910 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31920 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
31930 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
31940 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
31950 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
31960 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31970 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31980 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31990 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
319a0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
319b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
319c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
319d0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
319e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
319f0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
31a00 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
31a10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
31a20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
31a30 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
31a40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31a50 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
31a60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
31a70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31a80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
31a90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31aa0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
31ab0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31ac0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
31ad0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31ae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
31af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31b00 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
31b10 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
31b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31b30 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
31b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31b50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31b60 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
31b70 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
31b80 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
31b90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
31ba0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31bb0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
31bc0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
31bd0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
31be0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
31bf0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
31c00 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
31c10 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31c20 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
31c30 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
31c40 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
31c50 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
31c60 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
31c70 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
31c80 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
31c90 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
31ca0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
31cb0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
31cc0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
31cd0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
31ce0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
31cf0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
31d00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
31d10 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
31d20 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
31d30 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
31d40 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
31d50 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
31d60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31d70 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
31d80 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
31d90 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
31da0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
31db0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
31dc0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
31dd0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
31de0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
31df0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
31e00 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
31e10 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
31e20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
31e30 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
31e40 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
31e50 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
31e60 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
31e70 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
31e80 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
31e90 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
31ea0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
31eb0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31ec0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
31ed0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
31ee0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
31ef0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
31f00 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
31f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
31f20 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
31f30 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
31f40 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
31f50 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
31f60 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
31f70 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
31f80 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
31f90 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
31fa0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
31fb0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
31fc0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
31fd0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
31fe0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31ff0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
32000 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
32010 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
32020 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
32030 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
32040 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
32050 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
32060 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
32070 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32080 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
32090 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
320a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
320b0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
320c0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
320d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
320e0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
320f0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
32100 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
32110 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
32120 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
32130 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32140 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
32150 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
32160 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
32170 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
32180 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
32190 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
321a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
321b0 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
321c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
321d0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
321e0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
321f0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
32200 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
32210 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
32220 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
32230 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
32240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
32250 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
32260 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32270 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
32280 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
32290 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
322a0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
322b0 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
322c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
322d0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
322e0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
322f0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32300 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32310 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32320 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32330 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
32340 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61   void *sqlite3_a
32350 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32360 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32370 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
32380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32390 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
323a0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
323b0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
323c0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
323d0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
323e0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
323f0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
32400 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
32410 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
32420 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32430 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32440 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32450 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32460 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32470 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
32480 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
32490 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
324a0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
324b0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
324c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
324d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
324e0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
324f0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32500 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32510 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32520 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
32530 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
32540 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32550 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32560 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32570 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
32580 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
32590 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
325a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
325b0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
325c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
325d0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
325e0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
325f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32600 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32610 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32630 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32640 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32660 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32670 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32680 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32690 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
326a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
326b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
326c0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
326d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
326e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
326f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32700 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
32710 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
32720 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32730 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
32740 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
32750 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
32760 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
32770 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
32780 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
32790 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
327a0 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
327b0 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
327c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
327d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
327e0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
327f0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
32800 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
32810 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
32820 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
32830 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
32840 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
32850 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
32860 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
32870 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
32880 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
32890 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
328a0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
328b0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
328c0 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
328d0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
328e0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
328f0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
32900 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
32910 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
32920 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
32930 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
32940 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
32950 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
32960 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
32970 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
32980 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
32990 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
329a0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
329b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
329c0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
329d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
329e0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
329f0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
32a00 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
32a10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
32a20 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
32a30 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
32a40 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
32a50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32a60 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
32a70 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
32a80 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
32a90 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
32aa0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
32ab0 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
32ac0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32ad0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
32ae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
32af0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32b00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
32b10 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
32b20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
32b30 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
32b40 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
32b50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32b60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32b70 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
32b80 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
32b90 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
32ba0 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
32bb0 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
32bc0 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
32bd0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
32be0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
32bf0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
32c00 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
32c10 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
32c20 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
32c30 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
32c40 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
32c50 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32c60 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
32c70 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
32c80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32c90 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32ca0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
32cb0 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
32cc0 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
32cd0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
32ce0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
32cf0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
32d00 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
32d10 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
32d20 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
32d30 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
32d40 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
32d50 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
32d60 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
32d70 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
32d80 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
32d90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32da0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
32db0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
32dc0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
32dd0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
32de0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
32df0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
32e00 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
32e10 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
32e20 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
32e30 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
32e40 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
32e50 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
32e60 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
32e70 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
32e80 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
32e90 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
32ea0 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
32eb0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
32ec0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
32ed0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
32ee0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32ef0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
32f00 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
32f10 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
32f20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32f30 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32f40 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
32f50 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
32f60 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
32f70 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
32f80 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
32f90 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
32fa0 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
32fb0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
32fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
32fd0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
32fe0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
32ff0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
33000 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
33010 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
33020 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
33030 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
33040 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
33050 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
33060 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
33070 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
33080 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
33090 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
330a0 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
330b0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
330c0 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
330d0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
330e0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
330f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
33100 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33110 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33120 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33130 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
33140 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
33150 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33160 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
33170 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33180 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33190 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
331a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
331b0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
331c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
331d0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
331e0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
331f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
33200 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
33210 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
33220 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
33230 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
33240 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
33250 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
33260 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
33270 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
33280 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
33290 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
332a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
332b0 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
332c0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
332d0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
332e0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
332f0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
33300 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
33310 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
33320 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
33330 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
33340 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
33350 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
33360 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
33370 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
33380 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
33390 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
333a0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
333b0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
333c0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
333d0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
333e0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
333f0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
33400 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
33410 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
33420 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
33430 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
33440 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
33450 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64  pilers..*/.typed
33460 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
33470 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33480 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
33490 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
334a0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
334b0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
334c0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
334d0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
334e0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
334f0 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
33500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
33510 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
33520 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
33530 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
33540 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
33550 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
33560 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
33570 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
33580 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
33590 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
335a0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
335b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
335c0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
335d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
335e0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
335f0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
33600 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
33610 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
33620 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
33630 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
33640 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
33650 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
33660 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
33670 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
33680 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
33690 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
336a0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
336b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
336c0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
336d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
336e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
336f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33700 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
33710 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33720 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
33730 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33740 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33750 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
33760 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
33770 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
33780 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
33790 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
337a0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
337b0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
337c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
337d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
337e0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
337f0 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
33800 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
33810 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
33820 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33830 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
33840 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
33850 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
33860 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
33870 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
33880 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
33890 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
338a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
338b0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
338c0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
338d0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
338e0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
338f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33900 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
33910 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
33920 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
33930 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
33940 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
33950 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33960 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33970 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33980 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
33990 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
339a0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
339b0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
339c0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
339d0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
339e0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
339f0 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
33a00 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
33a10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33a20 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33a30 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
33a40 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
33a50 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
33a60 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
33a70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
33a80 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
33a90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
33aa0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
33ab0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
33ac0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
33ad0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
33ae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33af0 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
33b00 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
33b10 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
33b20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
33b30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
33b40 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
33b50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33b60 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
33b70 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
33b80 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
33b90 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
33ba0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
33bb0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
33bc0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
33bd0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
33be0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33bf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33c00 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
33c10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33c20 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
33c30 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
33c40 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
33c50 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
33c60 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
33c70 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
33c80 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
33c90 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
33ca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33cb0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33cc0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33cd0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33ce0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33cf0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33d00 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
33d10 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
33d20 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
33d30 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33d40 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33d50 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33d60 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33d70 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33d80 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
33d90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33da0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
33db0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
33dc0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
33dd0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
33de0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
33df0 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
33e00 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
33e10 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
33e20 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
33e30 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
33e40 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33e50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33e60 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33e70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33e80 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
33e90 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
33ea0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
33eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33ec0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
33ed0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
33ee0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33ef0 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33f00 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33f10 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33f20 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
33f30 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
33f40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33f50 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33f60 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
33f70 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33f80 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  hrow an.** error
33f90 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
33fb0 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
33fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33fd0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
33fe0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33ff0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34000 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34010 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34020 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
34030 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
34040 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
34050 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
34060 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
34070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
34080 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  nt64() interface
34090 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
340a0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
340b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
340c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
340d0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73   be the 64-bit s
340e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
340f0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
34100 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
34110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34120 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
34130 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34140 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34150 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34160 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34170 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34180 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
34190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
341a0 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
341b0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
341c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
341d0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
341e0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
341f0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
34200 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
34210 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34220 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34230 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34240 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
34250 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
34260 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
34270 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
34280 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34290 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
342a0 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
342b0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
342c0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
342d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65  .** ^SQLite take
342e0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
342f0 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
34300 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
34310 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34320 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
34330 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34340 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20  erfaces..** ^If 
34350 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
34360 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34370 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34380 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
34390 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
343a0 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
343b0 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
343c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
343d0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
343e0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
343f0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  r..** ^If the 3r
34400 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34410 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34420 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34430 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
34440 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
34450 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
34460 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
34470 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
34480 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
34490 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
344a0 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
344b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
344c0 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
344d0 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70  t.  If the 3rd p
344e0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
344f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
34500 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65  t.** must be the
34510 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74   byte offset int
34520 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  o the string whe
34530 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
34540 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61  nator would.** a
34550 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72  ppear if the str
34560 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65  ing where NUL te
34570 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
34580 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
34590 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
345a0 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74   string at a byt
345b0 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73  e offset that is
345c0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76   less than the v
345d0 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a  alue of the 3rd.
345e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ** parameter, th
345f0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
34600 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e   string will con
34610 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
34620 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65  Ls and the.** re
34630 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
34640 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e  ons operating on
34650 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d   strings with em
34660 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
34670 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66  ndefined..** ^If
34680 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
34690 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
346a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
346b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
346c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
346d0 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
346e0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
346f0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
34700 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
34710 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
34720 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
34730 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
34740 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
34750 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
34760 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
34770 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34780 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34790 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
347a0 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
347b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
347c0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
347d0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
347e0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
347f0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
34800 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
34810 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
34820 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
34830 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
34840 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
34850 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
34860 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
34870 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
34880 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
34890 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
348a0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
348b0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
348c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
348d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
348e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
348f0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
34900 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
34910 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
34920 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
34930 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
34940 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
34950 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
34960 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
34970 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
34980 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34990 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
349a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
349b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
349c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
349d0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
349e0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
349f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34a00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34a10 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
34a20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34a30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34a40 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
34a50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34a60 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
34a70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34a80 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
34a90 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34aa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34ab0 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
34ac0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
34ad0 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
34ae0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
34af0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
34b00 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
34b10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b20 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
34b30 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
34b40 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
34b50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34b60 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
34b70 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
34b80 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34b90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34ba0 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
34bb0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
34bc0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
34bd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34be0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
34bf0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34c00 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
34c10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34c20 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
34c30 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
34c40 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
34c50 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
34c60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34c70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34c80 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
34c90 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
34ca0 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
34cb0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34cc0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
34cd0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34cf0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34d00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34d10 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34d20 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
34d30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
34d40 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
34d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34d60 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
34d70 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34d80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
34d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34da0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
34db0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
34dc0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34dd0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
34de0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34df0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  t void*, int);.S
34e00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
34e10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34e20 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
34e30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
34e40 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34e50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34e60 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
34e70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
34e80 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
34e90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34ea0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
34eb0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
34ec0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
34ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34ee0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34ef0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
34f00 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34f10 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
34f20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34f30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34f40 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34f50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34f60 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
34f70 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
34f80 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34f90 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
34fa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34fb0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
34fc0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34fd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
34fe0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34ff0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
35000 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35010 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
35020 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
35030 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35040 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35050 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35060 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35070 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35080 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
35090 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
350a0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
350b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
350c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
350d0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
350e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
350f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35100 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
35110 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
35120 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35130 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35140 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
35150 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
35160 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
35170 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
35180 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
35190 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
351a0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
351b0 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
351c0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
351d0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
351e0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
351f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35200 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
35210 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
35220 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
35230 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
35240 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
35250 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
35260 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35270 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
35280 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35290 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
352a0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
352b0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
352c0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
352d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
352e0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
352f0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
35300 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
35310 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
35320 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
35330 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
35340 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
35350 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
35360 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
35370 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
35380 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
35390 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
353a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
353b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
353c0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
353d0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
353e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
353f0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
35400 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
35410 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35420 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
35430 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
35440 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
35450 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
35460 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
35470 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
35480 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35490 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
354a0 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
354b0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
354c0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
354d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
354e0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
354f0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
35500 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
35510 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
35520 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
35530 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
35540 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
35550 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
35560 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
35570 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
35580 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
35590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
355a0 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
355b0 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74  , is an applicat
355c0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
355d0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a   that is passed.
355e0 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ** through as th
355f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35600 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
35610 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
35620 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
35630 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  fifth argument, 
35640 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20  xCallback, is a 
35650 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
35660 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35670 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20  n..** ^Multiple 
35680 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35690 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  ons can be regis
356a0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
356b0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a  same name but.**
356c0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
356d0 65 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74  eTextRep paramet
356e0 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77  ers and SQLite w
356f0 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65  ill use whicheve
35700 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  r.** function re
35710 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
35720 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
35730 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a  transformation..
35740 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c  ** ^If the xCall
35750 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
35760 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
35770 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35780 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e  n is.** deleted.
35790 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c    ^When all coll
357a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
357b0 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20  having the same 
357c0 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64  name are deleted
357d0 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74  ,.** that collat
357e0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
357f0 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   usable..**.** ^
35800 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
35810 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20  nction callback 
35820 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
35830 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41  a copy of the pA
35840 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  rg .** applicati
35850 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35860 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72  and with two str
35870 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f  ings in the enco
35880 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a  ding specified.*
35890 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65  * by the eTextRe
358a0 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65  p argument.  The
358b0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
358c0 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20  ion must return 
358d0 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68  an.** integer th
358e0 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  at is negative, 
358f0 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76  zero, or positiv
35900 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73  e.** if the firs
35910 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
35920 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c   than, equal to,
35930 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
35940 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20   the second,.** 
35950 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
35960 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35970 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ion must always 
35980 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
35990 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20  answer.** given 
359a0 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e  the same inputs.
359b0 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65    If two or more
359c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
359d0 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65  ions are registe
359e0 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  red.** to the sa
359f0 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  me collation nam
35a00 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65  e (using differe
35a10 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75  nt eTextRep valu
35a20 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20  es) then all.** 
35a30 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75  must give an equ
35a40 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77  ivalent answer w
35a50 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68  hen invoked with
35a60 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69   equivalent stri
35a70 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c  ngs..** The coll
35a80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35a90 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c  ust obey the fol
35aa0 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65  lowing propertie
35ab0 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72  s for all.** str
35ac0 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43  ings A, B, and C
35ad0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
35ae0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65  <li> If A==B the
35af0 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  n B==A..** <li> 
35b00 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43  If A==B and B==C
35b10 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c   then A==C..** <
35b20 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48  li> If A&lt;B TH
35b30 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c  EN B&gt;A..** <l
35b40 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64  i> If A&lt;B and
35b50 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c   B&lt;C then A&l
35b60 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  t;C..** </ol>.**
35b70 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69  .** If a collati
35b80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  ng function fail
35b90 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f  s any of the abo
35ba0 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  ve constraints a
35bb0 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61  nd that.** colla
35bc0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
35bd0 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64    registered and
35be0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
35bf0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
35c00 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  te.** is undefin
35c10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
35c20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35c30 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
35c40 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
35c50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35c60 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61  ().** with the a
35c70 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65  ddition that the
35c80 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
35c90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
35ca0 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68   pArg when.** th
35cb0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35cc0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e  tion is deleted.
35cd0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66  .** ^Collating f
35ce0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c  unctions are del
35cf0 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  eted when they a
35d00 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
35d10 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20   later.** calls 
35d20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  to the collation
35d30 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
35d40 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a  ons or when the.
35d50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
35d60 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73  nection] is clos
35d70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
35d80 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
35d90 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20  * ^The xDestroy 
35da0 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e  callback is <u>n
35db0 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66  ot</u> called if
35dc0 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   the .** sqlite3
35dd0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35de0 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20  n_v2() function 
35df0 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74  fails.  Applicat
35e00 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65  ions that invoke
35e10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35e20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35e30 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  ) with a non-NUL
35e40 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d  L xDestroy argum
35e50 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63  ent should .** c
35e60 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
35e70 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65  code and dispose
35e80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35e90 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
35ea0 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72  .** themselves r
35eb0 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63  ather than expec
35ec0 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64  ting SQLite to d
35ed0 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20  eal with it for 
35ee0 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73  them..** This is
35ef0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
35f00 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69  every other SQLi
35f10 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  te interface.  T
35f20 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79  he inconsistency
35f30 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e   .** is unfortun
35f40 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62  ate but cannot b
35f50 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75  e changed withou
35f60 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77  t breaking backw
35f70 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69  ards .** compati
35f80 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  bility..**.** Se
35f90 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
35fa0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35fb0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
35fc0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35fd0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ded16()]..*/.SQL
35fe0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35ff0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36000 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
36010 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
36020 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
36030 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36040 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36050 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36060 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36070 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
36080 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
36090 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
360a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
360b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
360c0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
360d0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
360e0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
360f0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
36100 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
36110 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
36120 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
36130 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
36140 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
36150 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
36160 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
36170 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36180 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
36190 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
361a0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
361b0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
361c0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
361d0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
361e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
361f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
36200 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
36210 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
36220 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
36230 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
36240 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
36250 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
36260 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
36270 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
36280 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
36290 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
362a0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
362b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
362c0 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
362d0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
362e0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
362f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
36300 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
36310 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
36320 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
36330 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
36340 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36350 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
36360 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
36370 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
36380 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36390 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
363a0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
363b0 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
363c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
363d0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
363e0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
363f0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
36400 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
36410 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
36420 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
36430 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
36440 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
36450 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
36460 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
36470 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
36480 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
36490 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
364a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
364b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
364c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
364d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
364e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
364f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
36500 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36510 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
36520 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
36530 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
36540 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
36550 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
36560 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
36570 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
36580 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
36590 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
365a0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
365b0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
365c0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
365d0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
365e0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
365f0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
36600 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
36610 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
36620 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
36630 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
36640 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
36650 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
36660 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
36670 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
36680 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
36690 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
366a0 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
366b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
366c0 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
366d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
366e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
366f0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
36700 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
36710 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
36720 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36730 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
36740 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
36750 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
36760 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49  t char*).);.SQLI
36770 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36780 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
36790 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
367a0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
367b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
367c0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
367d0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
367e0 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
367f0 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
36800 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
36810 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
36820 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
36830 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
36840 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
36850 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
36860 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
36870 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
36880 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
36890 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
368a0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
368b0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
368c0 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
368d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  PI int sqlite3_k
368e0 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
368f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36900 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
36910 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36920 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36930 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36940 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
36950 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
36960 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76  nt sqlite3_key_v
36970 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
36980 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36990 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
369a0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
369b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
369c0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
369d0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
369e0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
369f0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
36a00 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
36a10 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
36a20 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
36a30 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
36a40 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
36a50 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
36a60 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
36a70 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
36a80 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
36a90 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
36aa0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
36ab0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
36ac0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
36ad0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
36ae0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
36af0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
36b00 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
36b10 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
36b20 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
36b30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
36b40 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
36b50 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36b60 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
36b70 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
36b80 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
36b90 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36ba0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
36bb0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54   key */.);.SQLIT
36bc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36bd0 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71  3_rekey_v2(.  sq
36be0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36c00 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
36c10 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
36c20 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
36c30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
36c40 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
36c50 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
36c60 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
36c70 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
36c80 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
36c90 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
36ca0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
36cb0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
36cc0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
36cd0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
36ce0 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
36cf0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
36d00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36d10 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
36d20 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
36d30 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
36d40 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
36d50 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
36d60 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
36d70 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
36d80 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
36d90 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
36da0 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
36db0 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
36dc0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
36dd0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
36de0 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
36df0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49  ll work..*/.SQLI
36e00 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
36e10 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
36e20 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
36e30 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
36e40 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
36e50 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
36e60 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
36e70 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
36e80 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
36e90 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
36ea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
36eb0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
36ec0 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
36ed0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
36ee0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
36ef0 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
36f00 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
36f10 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
36f20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
36f30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
36f40 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
36f50 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
36f60 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
36f70 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
36f80 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
36f90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
36fa0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
36fb0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
36fc0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
36fd0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
36fe0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
36ff0 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
37000 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
37010 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
37020 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
37030 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
37040 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
37050 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
37060 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
37070 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
37080 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
37090 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
370a0 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
370b0 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
370c0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
370d0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
370e0 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
370f0 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
37100 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
37110 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
37120 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
37130 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
37140 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
37150 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
37160 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
37170 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
37180 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
37190 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
371a0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
371b0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
371c0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
371d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
371e0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
371f0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
37200 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
37210 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
37220 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
37230 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
37240 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
37250 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
37260 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
37270 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
37280 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
37290 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
372a0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
372b0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
372c0 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
372d0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
372e0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
372f0 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
37300 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
37310 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
37320 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
37330 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
37340 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
37350 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
37360 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
37370 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
37380 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
37390 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
373a0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
373b0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
373c0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
373d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
373e0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
373f0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
37400 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
37410 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
37420 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
37430 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
37440 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
37450 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
37460 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
37470 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
37480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
37490 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
374a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
374b0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
374c0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
374d0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
374e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
374f0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
37500 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
37510 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
37520 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
37530 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
37540 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
37550 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37560 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
37570 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
37580 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
37590 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
375a0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
375b0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
375c0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
375d0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
375e0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
375f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
37600 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37610 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
37620 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
37630 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
37640 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
37650 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
37660 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
37670 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
37680 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
37690 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
376a0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
376b0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
376c0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
376d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
376e0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
376f0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
37700 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
37710 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
37720 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
37730 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
37740 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
37750 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
37760 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
37770 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
37780 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
37790 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ling [sqlite3_op
377a0 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  en] or [sqlite3_
377b0 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72  open_v2].  Other
377c0 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
377d0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
377e0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
377f0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
37800 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72  s may fail.  Her
37810 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70  e is an.** examp
37820 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20  le of how to do 
37830 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77  this using C++ w
37840 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20  ith the Windows 
37850 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c  Runtime:.**.** <
37860 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
37870 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74  .** LPCWSTR zPat
37880 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f  h = Windows::Sto
37890 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f  rage::Applicatio
378a0 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e  nData::Current->
378b0 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54  .** &nbsp;     T
378c0 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e  emporaryFolder->
378d0 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a  Path->Data();.**
378e0 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23   char zPathBuf&#
378f0 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26  91;MAX_PATH + 1&
37900 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28  #93;;.** memset(
37910 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a  zPathBuf, 0, siz
37920 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a  eof(zPathBuf));.
37930 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c  ** WideCharToMul
37940 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20  tiByte(CP_UTF8, 
37950 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50  0, zPath, -1, zP
37960 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a  athBuf, sizeof(z
37970 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62  PathBuf),.** &nb
37980 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55  sp;     NULL, NU
37990 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  LL);.** sqlite3_
379a0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d  temp_directory =
379b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
379c0 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29  ("%s", zPathBuf)
379d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
379e0 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49  ckquote>.*/.SQLI
379f0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
37a00 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
37a10 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
37a20 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
37a30 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
37a40 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
37a50 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
37a60 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
37a70 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
37a80 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
37a90 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
37aa0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
37ab0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
37ac0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
37ad0 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
37ae0 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
37af0 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
37b00 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
37b10 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
37b20 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
37b30 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
37b40 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
37b50 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
37b60 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
37b70 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
37b80 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
37b90 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
37ba0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
37bb0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
37bc0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
37bd0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
37be0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
37bf0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
37c00 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
37c10 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
37c20 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
37c30 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
37c40 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
37c50 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
37c60 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
37c70 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
37c80 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
37c90 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
37ca0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
37cb0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
37cc0 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
37cd0 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
37ce0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37cf0 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
37d00 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
37d10 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
37d20 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
37d30 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37d40 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37d50 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
37d60 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
37d70 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
37d80 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37d90 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37da0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
37db0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37dc0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
37dd0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
37de0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
37df0 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
37e00 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
37e10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37e20 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
37e30 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
37e40 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
37e50 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
37e60 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
37e70 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
37e80 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
37e90 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
37ea0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
37eb0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
37ec0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
37ed0 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
37ee0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37ef0 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
37f00 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
37f10 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
37f20 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37f30 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
37f50 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
37f60 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
37f70 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37f80 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
37f90 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
37fa0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
37fb0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
37fc0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
37fd0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
37fe0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
37ff0 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
38000 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
38010 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
38020 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
38030 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
38040 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
38050 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
38060 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
38070 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
38080 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
38090 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
380a0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
380b0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
380c0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
380d0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
380e0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
380f0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38100 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
38110 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ded..*/.SQLITE_A
38120 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
38130 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
38140 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
38150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38160 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
38170 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
38180 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
38190 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
381a0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
381b0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
381c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
381d0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
381e0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
381f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38200 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
38210 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
38220 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
38230 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
38240 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
38250 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
38260 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
38270 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
38280 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
38290 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
382a0 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
382b0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
382c0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
382d0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
382e0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
382f0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
38300 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
38310 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
38320 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
38330 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
38340 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
38350 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
38360 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
38370 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
38380 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
38390 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
383a0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
383b0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
383c0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
383d0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
383e0 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
383f0 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
38400 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
38410 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
38420 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
38430 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
38440 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
38450 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
38460 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
38470 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
38480 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
38490 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
384a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
384b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
384c0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
384d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
384e0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
384f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
38500 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
38510 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
38520 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
38530 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
38540 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
38550 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
38560 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
38570 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
38580 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
38590 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
385a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
385b0 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
385c0 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
385d0 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
385e0 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
385f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
38600 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
38610 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
38620 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
38630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38640 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
38650 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38660 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
38670 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
38680 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
38690 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
386a0 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
386b0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
386c0 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
386d0 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lace..*/.SQLITE_
386e0 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
386f0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
38700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
38710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38720 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e  Return The Filen
38730 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61  ame For A Databa
38740 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
38750 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38760 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e  _db_filename(D,N
38770 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
38780 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a