System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact da7dd2561c39f4025f1bfb7122f92c104ca080fa:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 36 22 0a 23 64 65 66 69 6e 65 20 53  .7.16".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 36 0a 23 64 65  MBER 3007016.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33  CE_ID      "2013
1070: 2d 30 33 2d 30 36 20 31 31 3a 34 34 3a 35 37 20  -03-06 11:44:57 
1080: 36 36 35 37 36 62 34 35 30 61 30 66 30 33 32 39  66576b450a0f0329
1090: 35 37 31 65 33 34 34 32 38 30 39 39 34 61 39 36  571e344280994a96
10a0: 34 63 39 36 37 66 38 66 22 0a 0a 2f 2a 0a 2a 2a  4c967f8f"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5600: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5610: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5630: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5640: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5650: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5670: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5690: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
56a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
56b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
56c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
56d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5700: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5710: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5720: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5730: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5740: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5750: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5760: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5770: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5780: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
57c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
57d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5800: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5810: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5820: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
5840: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
5850: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
5860: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5870: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5880: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20  INT_CHECK       
5890: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58a0: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  INT | (1<<8)).#d
58b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58c0: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f  STRAINT_COMMITHO
58d0: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  OK   (SQLITE_CON
58e0: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29  STRAINT | (2<<8)
58f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45  _CONSTRAINT_FORE
5910: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45  IGNKEY   (SQLITE
5920: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33  _CONSTRAINT | (3
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5950: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51  FUNCTION     (SQ
5960: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5970: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5980: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5990: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20  INT_NOTNULL     
59a0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
59b0: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  INT | (5<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b  STRAINT_PRIMARYK
59e0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29  STRAINT | (6<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47  _CONSTRAINT_TRIG
5a20: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  GER      (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37  _CONSTRAINT | (7
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51  UNIQUE       (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  INT_VTAB        
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f  INT | (9<<8))../
5ad0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5ae0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5af0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5b00: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5b10: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5b20: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5b30: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5b40: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5b50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5b60: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5b70: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5b80: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5b90: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5ba0: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5bb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5bc0: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5bd0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5be0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5bf0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5c00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5c10: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5c20: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5c30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5c40: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5c50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5c60: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5c70: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5c80: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5c90: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5ca0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5cb0: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5cc0: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5cd0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ce0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5cf0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5d00: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5d10: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5d20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5d30: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5d40: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5d50: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5d60: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5d80: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5d90: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5da0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5db0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5dc0: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5dd0: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5de0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5df0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5e10: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5e20: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5e30: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5e50: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5e60: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
5e70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5e80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
5e90: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
5ea0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
5eb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ec0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5ed0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5ee0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5ef0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5f10: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5f20: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5f30: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f40: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5f50: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5f60: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
5f70: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5f90: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5fa0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
5fb0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5fc0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5fd0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5fe0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5ff0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6000: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
6020: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6030: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6040: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6050: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6060: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
6070: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
6080: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
6090: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
60a0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
60b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
60c0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
60d0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
60e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
60f0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6100: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
6110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6120: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6130: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6140: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6160: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6170: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6180: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6190: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
61a0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
61b0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
61c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
61d0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
61e0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
61f0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
6200: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
6210: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
6220: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6230: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6240: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6250: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6260: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6270: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6280: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6290: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
62a0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
62b0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
62c0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
62d0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
62e0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
62f0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
6310: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
6320: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6330: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6340: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6350: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6360: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6370: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6380: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6390: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
63a0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
63b0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
63c0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
63d0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
63e0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
63f0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
6400: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
6410: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
6420: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6430: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6440: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6450: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6460: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6470: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6480: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6490: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
64a0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
64b0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
64c0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
64d0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
64e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
64f0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
6500: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6510: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
6520: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6530: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6540: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6550: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6560: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6570: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6580: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6590: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
65a0: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
65b0: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
65c0: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
65d0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
65e0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
65f0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
6600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6610: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6630: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6640: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6650: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6660: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6680: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6690: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
66a0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
66b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
66c0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
66d0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
66e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
66f0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
6700: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6710: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
6720: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6730: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6740: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6750: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6760: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6770: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6780: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6790: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
67a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
67b0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
67c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
67d0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
67e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
67f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6800: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6810: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
6820: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6840: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6850: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6870: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6880: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6890: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
68a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
68b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
68c0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
68d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
68e0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
68f0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6900: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6910: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6920: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6930: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6940: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6950: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6960: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6970: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6980: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6990: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
69a0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
69b0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
69d0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
69e0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
69f0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6a00: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6a10: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6a20: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6a30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6a40: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6a50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6a60: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6a70: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6a80: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6a90: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6aa0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6ab0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6ac0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6ad0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6ae0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6af0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6b00: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6b10: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6b20: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6b30: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6b40: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6b50: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6b60: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6b70: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6b80: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6b90: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6ba0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6bb0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6bc0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6bd0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6be0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6bf0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6c00: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6c10: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6c20: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6c30: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6c40: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6c50: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6c60: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6c70: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6c80: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6c90: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6ca0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6cb0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6cc0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6cd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6ce0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6cf0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6d00: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6d10: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6d20: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6d30: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6d40: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6d50: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6d60: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6d70: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6d80: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6d90: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6da0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6db0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6dc0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6dd0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6de0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
6df0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
6e00: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6e10: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6e20: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
6e30: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
6e40: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
6e50: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
6e60: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
6e70: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
6e80: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
6eb0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
6ec0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
6ed0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6ee0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6ef0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
6f00: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
6f10: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
6f20: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
6f30: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
6f40: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
6f50: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
6f60: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
6f70: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6f80: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
6f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6fa0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
6fb0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
6fc0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6fd0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
6fe0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
6ff0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7000: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7010: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7020: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7030: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7040: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7050: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7060: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7070: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7080: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7090: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
70a0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
70b0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
70c0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
70d0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
70e0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
70f0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7100: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7110: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7120: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7130: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7140: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7150: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7160: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7170: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7180: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7190: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
71a0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
71b0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
71c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
71d0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
71e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
71f0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7200: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7210: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7220: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7230: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7240: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7250: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7260: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7270: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7280: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7290: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
72a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
72b0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
72c0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
72d0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
72e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
72f0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7310: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7320: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7330: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7340: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7350: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7360: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7370: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7380: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7390: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
73a0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
73b0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
73c0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
73d0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
73e0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
73f0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7400: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7410: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7420: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7430: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7440: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7450: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7460: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7470: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7480: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7490: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
74a0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
74b0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
74c0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
74d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
74e0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
74f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7500: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7510: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7520: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7530: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7540: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7550: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7560: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7570: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7580: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7590: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
75a0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
75b0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
75c0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
75d0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
75e0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
75f0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7600: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7610: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7620: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7630: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7640: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7650: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7660: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7670: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7680: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7690: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
76a0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
76b0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
76c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
76d0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
76e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
76f0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7700: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7710: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7720: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7730: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7740: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7750: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7760: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7770: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7780: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7790: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
77a0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
77b0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
77c0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
77d0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
77e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
77f0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7800: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7810: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7820: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7830: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7840: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7850: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7860: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7870: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7880: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7890: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
78a0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
78b0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
78c0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
78d0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
78e0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
78f0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7900: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7910: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7920: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7930: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7940: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7950: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7960: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7970: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7980: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7990: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
79a0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
79b0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
79c0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
79d0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
79e0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
79f0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7a00: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7a10: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7a20: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7a30: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7a40: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7a50: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7a60: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7a70: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7a80: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7a90: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7aa0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7ab0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7ac0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7ad0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7ae0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7af0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7b00: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7b10: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7b20: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7b30: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7b40: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7b50: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7b60: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7b70: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7b80: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7b90: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7ba0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7bb0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7bc0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7bd0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7be0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7bf0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7c00: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7c10: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7c20: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7c30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7c40: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7c50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7c60: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7c70: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7c90: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7ca0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7cb0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7cc0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7cd0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ce0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7cf0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7d00: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7d10: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7d20: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7d30: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7d40: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7d50: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7d60: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7d70: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7d80: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7d90: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7da0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7db0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7dc0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7dd0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7de0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
7df0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7e00: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7e10: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7e20: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
7e30: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7e40: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
7e50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7e60: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
7e70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7e80: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
7e90: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ea0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
7eb0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ec0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
7ed0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7ee0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
7ef0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7f00: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
7f10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7f20: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7f30: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
7f40: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7f50: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
7f60: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
7f70: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
7f80: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
7f90: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7fa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
7fb0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
7fc0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7fd0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7fe0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7ff0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8000: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8010: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8020: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8030: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8040: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8050: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8060: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8070: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8080: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8090: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
80a0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
80b0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
80c0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
80d0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
80e0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
80f0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8110: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8120: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8130: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8140: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8150: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8160: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8170: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8180: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8190: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
81a0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
81b0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
81c0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
81d0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
81e0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
81f0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8200: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8210: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8220: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8230: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8240: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8250: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8260: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8270: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8280: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8290: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
82a0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
82b0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
82c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
82d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
82e0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
82f0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8300: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8310: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8320: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8330: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8340: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8350: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8360: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8370: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8380: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8390: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
83a0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
83b0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
83c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
83d0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
83e0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
83f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8400: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8410: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8420: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8430: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8440: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8450: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8460: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8470: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8480: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8490: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
84a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
84b0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
84c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
84d0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
84e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
84f0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8500: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8510: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8520: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8530: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8550: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8560: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8570: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8580: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8590: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85a0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
85b0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
85c0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
85d0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
85e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
85f0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8600: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8610: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8630: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8640: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8650: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8660: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8670: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8680: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8690: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
86a0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
86b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
86c0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
86d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
86e0: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
86f0: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8700: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8710: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8720: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8730: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8740: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8750: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8760: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8770: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8780: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8790: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
87a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
87b0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
87c0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
87d0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
87e0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
87f0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8800: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8810: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8820: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8830: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8840: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8850: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8860: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8870: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8880: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8890: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
88a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
88b0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
88c0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
88d0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
88e0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
88f0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8900: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8910: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8920: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8930: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8940: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8950: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8960: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8970: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
8980: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8990: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
89a0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
89b0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
89c0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
89d0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
89e0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
89f0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8a00: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8a10: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8a20: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8a30: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8a40: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8a50: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8a60: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8a70: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8a80: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8a90: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8aa0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8ab0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8ac0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8ad0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8ae0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8af0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8b00: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8b10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8b20: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8b30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8b40: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8b50: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8b60: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8b70: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8b80: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8b90: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8ba0: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8bb0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8bc0: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
8bd0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
8be0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
8bf0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
8c00: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8c10: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8c20: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8c30: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8c40: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8c50: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8c60: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8c70: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8c80: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8c90: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8ca0: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
8cb0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
8cc0: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
8cd0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
8ce0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
8cf0: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
8d00: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
8d10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8d20: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
8d30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8d40: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8d50: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8d60: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
8d70: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
8d80: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
8d90: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
8da0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
8db0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
8dc0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
8dd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8de0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
8df0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
8e00: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
8e10: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
8e20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8e30: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
8e40: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  ^(The [SQLITE_FC
8e50: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8e60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
8e70: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
8e80: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e   by.** SQLite an
8e90: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46  d sent to all VF
8ea0: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  Ses in place of 
8eb0: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53  a call to the xS
8ec0: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68  ync method.** wh
8ed0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
8ee0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b  connection has [
8ef0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8f00: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29  us] set to OFF.)
8f10: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61  ^.** Some specia
8f20: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64  lized VFSes need
8f30: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20   this signal in 
8f40: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65  order to operate
8f50: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68   correctly.** wh
8f60: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  en [PRAGMA synch
8f70: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
8f80: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
8f90: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73   is set, but mos
8fa0: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e  t .** VFSes do n
8fb0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
8fc0: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73  nal and should s
8fd0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
8fe0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41  his opcode..** A
8ff0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9000: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
9010: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9020: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a  l()] with this.*
9030: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  * opcode as doin
9040: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
9050: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9060: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9070: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20  d VFSes.** that 
9080: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9090: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
90b0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
90c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
90d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
90e0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
90f0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
9100: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
9110: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
9120: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
9130: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
9140: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9150: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9160: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9170: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9180: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9190: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
91a0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
91b0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
91c0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
91d0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
91e0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
91f0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
9200: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
9210: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
9220: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
9230: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
9240: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9250: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9260: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9270: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9280: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9290: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
92a0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
92b0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
92c0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
92d0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
92e0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
92f0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9300: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9310: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9320: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9330: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9340: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9350: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9360: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9370: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9380: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9390: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
93a0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
93b0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
93c0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
93d0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
93e0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
93f0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9400: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9410: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9420: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9430: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9440: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9450: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9460: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9470: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9480: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9490: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
94a0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
94b0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
94c0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
94d0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
94e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
94f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9500: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9510: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9520: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9530: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9540: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9550: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9560: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9570: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9580: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9590: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
95a0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
95b0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
95c0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
95d0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
95e0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
95f0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9600: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9610: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9620: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9630: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9640: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9650: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9660: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9670: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9680: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9690: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
96a0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
96b0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
96c0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
96d0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
96e0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
96f0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9700: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9710: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9720: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9730: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9740: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9750: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
9760: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
9770: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
9780: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
9790: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
97a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
97b0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
97c0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
97d0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
97e0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
97f0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9800: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9810: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9820: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9830: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9840: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
9850: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
9860: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
9870: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
9880: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
9890: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
98a0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
98b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
98c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
98d0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
98e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
98f0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
9900: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9910: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
9920: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
9930: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
9940: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
9950: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
9960: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
9970: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
9980: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
9990: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
99a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
99b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
99c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
99d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
99e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
99f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a00: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9a10: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9a20: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9a30: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9a40: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9a50: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
9a60: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9a70: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
9a80: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
9a90: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
9aa0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
9ab0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
9ac0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
9ad0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
9ae0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
9af0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
9b00: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
9b10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9b20: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9b30: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
9b40: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
9b50: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
9b60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
9b70: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
9b80: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
9b90: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
9ba0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
9bb0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
9bc0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
9bd0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
9be0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
9bf0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
9c00: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
9c10: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
9c20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9c30: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
9c40: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9c50: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
9c60: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
9c70: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
9c80: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
9c90: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
9ca0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
9cb0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
9cc0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
9cd0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
9ce0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
9cf0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
9d00: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
9d10: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
9d20: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
9d30: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
9d40: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
9d50: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
9d60: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
9d70: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
9d80: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9d90: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
9da0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
9db0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
9dc0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
9dd0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
9de0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
9df0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
9e00: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
9e10: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
9e20: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
9e30: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
9e40: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
9e50: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
9e60: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
9e70: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
9e80: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
9e90: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
9ea0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
9eb0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
9ec0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
9ed0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
9ee0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
9ef0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9f00: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
9f10: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
9f20: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
9f30: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
9f40: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9f50: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
9f60: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
9f70: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
9f80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
9f90: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
9fa0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9fb0: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
9fc0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
9fd0: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
9fe0: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
9ff0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a000: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a010: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
a020: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
a030: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
a040: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
a050: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
a060: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
a070: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a080: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
a090: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
a0a0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
a0b0: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a0c0: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a0d0: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a0e0: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a0f0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a110: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a120: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a130: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a140: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a150: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a160: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a170: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a180: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a190: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a1a0: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a1b0: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a1c0: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a1d0: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a1e0: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a1f0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a200: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a210: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a220: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a230: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a240: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
a250: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
a260: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
a270: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
a280: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
a290: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a2a0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
a2b0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a2c0: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
a2d0: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
a2e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
a2f0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
a300: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
a310: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
a320: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
a330: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
a340: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
a350: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a360: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a370: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
a380: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
a390: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
a3a0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
a3b0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
a3c0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
a3d0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
a3e0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
a3f0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
a400: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
a410: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
a420: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
a430: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
a440: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
a450: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
a460: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
a470: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
a480: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
a490: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
a4a0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
a4b0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
a4c0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
a4d0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
a4e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a4f0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
a500: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73  NDLER]].** ^This
a510: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
a520: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
a530: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
a540: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
a550: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
a560: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
a570: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
a580: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
a590: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
a5a0: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
a5b0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
a5c0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
a5d0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
a5e0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
a5f0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
a600: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
a610: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
a620: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
a630: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
a640: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
a650: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
a660: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
a670: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
a680: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
a690: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
a6a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
a6b0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
a6c0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
a6d0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
a6e0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
a6f0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
a700: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
a710: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
a720: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
a730: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
a740: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
a750: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
a760: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
a770: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
a780: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a790: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
a7a0: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
a7b0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
a7c0: 76 6f 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63  voke this file-c
a7d0: 6f 6e 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53  ontrol to have S
a7e0: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61  QLite generate a
a7f0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
a800: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65  lename using the
a810: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
a820: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64  that is followed
a830: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20   to generate.** 
a840: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
a850: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62  mes for TEMP tab
a860: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e  les and other in
a870: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68  ternal uses.  Th
a880: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  e.** argument sh
a890: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a  ould be a char**
a8a0: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66   which will be f
a8b0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66  illed with the f
a8c0: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74  ilename.** writt
a8d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a8e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a8f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
a900: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f    The caller sho
a910: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73  uld.** invoke [s
a920: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
a930: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20  n the result to 
a940: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c  avoid a memory l
a950: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  eak..**.** </ul>
a960: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
a980: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a990: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
a9a0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
a9b0: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
a9c0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a9d0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
a9e0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
a9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa00: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
aa20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
aa30: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
aa40: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
aa50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
aa60: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
aa70: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
aa80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
aa90: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
aaa0: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
aab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
aac0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
aad0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
aae0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
aaf0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
ab00: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
ab10: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ab20: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
ab30: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
ab40: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
ab50: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
ab60: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
ab70: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
ab80: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
ab90: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
aba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
abb0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
abc0: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
abd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
abe0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
abf0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ac00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ac10: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ac20: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ac30: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
ac40: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ac50: 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   16../*.** CAPI3
ac60: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
ac70: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
ac80: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
ac90: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
aca0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
acb0: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
acc0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
acd0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
ace0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
acf0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
ad00: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
ad10: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
ad20: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
ad30: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
ad40: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
ad50: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
ad60: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
ad70: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
ad80: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
ad90: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
ada0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
adb0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
adc0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
add0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
ade0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
adf0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
ae00: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
ae10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
ae20: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
ae30: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
ae40: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
ae50: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
ae60: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
ae70: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
ae80: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
ae90: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
aea0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
aeb0: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
aec0: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
aed0: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
aee0: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
aef0: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
af00: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
af10: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
af20: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
af30: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
af40: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
af50: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
af60: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
af70: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
af80: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
af90: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
afa0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
afb0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
afc0: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
afd0: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
afe0: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
aff0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
b000: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
b010: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
b020: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
b030: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
b040: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
b050: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
b060: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
b070: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
b080: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
b090: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
b0a0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
b0b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
b0c0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
b0d0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
b0e0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
b0f0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
b100: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
b110: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
b120: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
b130: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b140: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
b150: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
b160: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
b170: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
b180: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
b190: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
b1a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
b1b0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
b1c0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
b1d0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
b1e0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
b1f0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
b200: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
b210: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
b220: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
b230: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
b240: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
b250: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
b260: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
b270: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
b280: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
b290: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
b2a0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
b2b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
b2c0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
b2d0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
b2e0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
b2f0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
b300: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
b310: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
b320: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
b330: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
b340: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
b350: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
b360: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
b370: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
b380: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
b390: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
b3a0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
b3b0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
b3c0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
b3d0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
b3e0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
b3f0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
b400: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
b410: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
b420: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
b430: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b440: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
b450: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
b460: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
b470: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
b480: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
b490: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
b4a0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
b4b0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
b4c0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
b4d0: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
b4e0: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
b4f0: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
b500: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
b510: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
b520: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
b530: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
b540: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
b550: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
b560: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
b570: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
b580: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
b590: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
b5a0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
b5b0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
b5c0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
b5d0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
b5e0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
b5f0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
b600: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
b610: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
b620: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
b630: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
b640: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
b650: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
b660: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
b670: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
b680: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
b690: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
b6a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
b6b0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
b6c0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
b6d0: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
b6e0: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
b6f0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
b700: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
b710: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
b720: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
b730: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
b740: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
b750: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
b760: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
b770: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
b780: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
b790: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
b7a0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
b7b0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
b7c0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
b7d0: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
b7e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
b7f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
b800: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
b810: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
b820: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
b830: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
b840: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
b850: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
b860: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
b870: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
b880: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
b890: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
b8a0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
b8b0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
b8c0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
b8d0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
b8e0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
b8f0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
b900: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
b910: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
b920: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
b930: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
b940: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
b950: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
b960: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
b970: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
b980: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
b990: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
b9a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
b9b0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b9c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
b9d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
b9e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
b9f0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
ba00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
ba10: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
ba20: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ba30: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
ba40: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ba50: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
ba60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ba70: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
ba80: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ba90: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
baa0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
bab0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
bac0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bad0: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
bae0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
baf0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
bb00: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
bb10: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
bb20: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
bb30: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
bb40: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
bb50: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
bb60: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
bb70: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
bb80: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
bb90: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
bba0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
bbb0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
bbc0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
bbd0: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
bbe0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
bbf0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
bc00: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
bc10: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
bc20: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
bc30: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
bc40: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
bc50: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
bc60: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
bc70: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
bc80: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
bc90: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
bca0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
bcb0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
bcc0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
bcd0: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
bce0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
bcf0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
bd00: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
bd10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
bd20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bd30: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
bd40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
bd50: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
bd60: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
bd70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
bd80: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
bd90: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
bda0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
bdb0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
bdc0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
bdd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
bde0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
bdf0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
be00: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
be10: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
be20: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
be30: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
be40: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
be50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
be60: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
be70: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
be80: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
be90: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
bea0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
beb0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
bec0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
bed0: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
bee0: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
bef0: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
bf00: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
bf10: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
bf20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
bf30: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
bf40: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
bf50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
bf60: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
bf70: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
bf80: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
bf90: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
bfa0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
bfb0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
bfc0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
bfd0: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
bfe0: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
bff0: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
c000: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
c010: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
c020: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
c030: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
c040: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
c050: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
c060: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
c070: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
c080: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
c090: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
c0a0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
c0b0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
c0c0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
c0d0: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
c0e0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
c0f0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
c100: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
c110: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
c120: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
c130: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
c140: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c150: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
c160: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
c170: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
c180: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
c190: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
c1a0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
c1b0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
c1c0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
c1d0: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
c1e0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
c1f0: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
c200: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
c210: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
c220: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
c230: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
c240: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
c250: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
c260: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
c270: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
c280: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c290: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
c2a0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
c2b0: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
c2c0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
c2d0: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
c2e0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c2f0: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
c300: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
c310: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
c320: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
c330: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
c340: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
c350: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c360: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
c370: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
c380: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
c390: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
c3a0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
c3b0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
c3c0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
c3d0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
c3e0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
c3f0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
c400: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
c410: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
c420: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
c430: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
c440: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
c450: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
c460: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c470: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
c480: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
c490: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
c4a0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
c4b0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
c4c0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
c4d0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
c4e0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
c4f0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
c500: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
c510: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
c520: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
c530: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
c540: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
c550: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
c560: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
c570: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
c580: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
c590: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
c5a0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
c5b0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
c5c0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
c5d0: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
c5e0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
c5f0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
c600: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
c610: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
c620: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
c630: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
c640: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
c650: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
c660: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
c670: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
c680: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
c690: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
c6a0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
c6b0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
c6c0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
c6d0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
c6e0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
c6f0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
c700: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
c710: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
c720: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
c730: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
c740: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
c750: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
c760: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
c770: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
c780: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
c790: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
c7a0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
c7b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c7c0: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
c7d0: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
c7e0: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
c7f0: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
c800: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
c810: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
c820: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
c830: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
c840: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
c850: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
c860: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c870: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
c880: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
c890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
c8a0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
c8b0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
c8c0: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
c8d0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
c8e0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
c8f0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
c900: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
c910: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
c920: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
c930: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
c940: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
c950: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
c960: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
c970: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
c980: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
c990: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
c9a0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
c9b0: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
c9c0: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
c9d0: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
c9e0: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
c9f0: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
ca00: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
ca10: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
ca20: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
ca30: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
ca40: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
ca50: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
ca60: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
ca70: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
ca80: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
ca90: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
caa0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
cab0: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
cac0: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
cad0: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
cae0: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
caf0: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
cb00: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
cb10: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
cb20: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
cb30: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
cb40: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
cb50: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
cb60: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
cb70: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
cb80: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
cb90: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
cba0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
cbb0: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
cbc0: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
cbd0: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
cbe0: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
cbf0: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
cc00: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
cc10: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
cc20: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
cc30: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
cc40: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
cc50: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
cc60: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
cc70: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
cc80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
cc90: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
cca0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
ccb0: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
ccc0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
ccd0: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
cce0: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
ccf0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
cd00: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
cd10: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
cd20: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
cd30: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
cd40: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
cd50: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
cd60: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
cd70: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
cd80: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
cd90: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
cda0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
cdb0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
cdc0: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
cdd0: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
cde0: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
cdf0: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
ce00: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
ce10: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
ce20: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
ce30: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
ce40: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
ce50: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
ce60: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
ce70: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
ce80: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ce90: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
cea0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
ceb0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
cec0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
ced0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
cee0: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
cef0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cf00: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
cf10: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
cf20: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
cf30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cf40: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
cf50: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
cf60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
cf70: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
cf80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cf90: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
cfa0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
cfb0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
cfc0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
cfd0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
cfe0: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
cff0: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
d000: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d010: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
d020: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
d030: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
d040: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
d050: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
d060: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
d070: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
d080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
d090: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
d0a0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
d0b0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
d0c0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d0d0: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
d0e0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d0f0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
d100: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d110: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
d120: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
d130: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
d140: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
d150: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
d160: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d170: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d180: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
d190: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d1a0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
d1b0: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
d1c0: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
d1d0: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
d1e0: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
d1f0: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d200: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
d210: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
d220: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
d230: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d240: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d250: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
d260: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d270: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
d280: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
d290: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
d2a0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
d2b0: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
d2c0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d2d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d2e0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
d2f0: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
d300: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d310: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
d320: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d330: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d340: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
d350: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
d360: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d370: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d380: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
d390: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d3a0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d3b0: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
d3c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d3d0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d3e0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
d3f0: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
d400: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
d410: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
d420: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
d430: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
d440: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
d450: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d460: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
d470: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
d480: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d490: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d4a0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
d4b0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
d4c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
d4d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
d4e0: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
d4f0: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
d500: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
d510: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
d520: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
d530: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
d540: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
d550: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d560: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
d570: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
d580: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
d590: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
d5a0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
d5b0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d5c0: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
d5d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d5e0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
d5f0: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
d600: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
d610: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
d620: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
d630: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
d640: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
d650: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
d660: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
d670: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
d680: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
d690: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
d6a0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
d6b0: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
d6c0: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
d6d0: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
d6e0: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
d6f0: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
d700: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
d710: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
d720: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d730: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
d740: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d750: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
d760: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
d770: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
d780: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
d790: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
d7a0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
d7b0: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
d7c0: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
d7d0: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
d7e0: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
d7f0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d800: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
d810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
d820: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
d830: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
d840: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
d850: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
d860: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d870: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
d880: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
d890: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
d8a0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
d8b0: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
d8c0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
d8d0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
d8e0: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
d8f0: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
d900: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
d910: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
d920: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
d930: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
d940: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
d950: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
d960: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
d970: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
d980: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
d990: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d9a0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
d9b0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
d9c0: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
d9d0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
d9e0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
d9f0: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
da00: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
da10: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
da20: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
da30: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
da40: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
da50: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
da60: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
da70: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
da80: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
da90: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
daa0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
dab0: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
dac0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
dad0: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
dae0: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
daf0: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
db00: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
db10: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
db20: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
db30: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
db40: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
db50: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
db60: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
db70: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
db80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
db90: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
dba0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
dbb0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
dbc0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
dbd0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
dbe0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
dbf0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
dc00: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
dc10: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
dc20: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
dc30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
dc40: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
dc50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
dc60: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
dc70: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
dc80: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
dc90: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
dca0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
dcb0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
dcc0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
dcd0: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
dce0: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
dcf0: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
dd00: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
dd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
dd20: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
dd30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
dd40: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
dd50: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
dd60: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
dd70: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
dd80: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
dd90: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
dda0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
ddb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ddc0: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
ddd0: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
dde0: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
ddf0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
de00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
de10: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
de20: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
de30: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
de40: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
de50: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
de60: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
de70: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
de80: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
de90: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
dea0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
deb0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
dec0: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
ded0: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
dee0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
def0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
df00: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
df10: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
df20: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
df30: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
df40: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
df50: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
df60: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
df70: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
df80: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
df90: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
dfa0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
dfb0: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
dfc0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
dfd0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
dfe0: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
dff0: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
e000: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e010: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
e020: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
e030: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
e040: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
e050: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e060: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e070: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
e080: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
e090: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
e0a0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
e0b0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e0c0: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
e0d0: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
e0e0: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
e0f0: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
e100: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
e110: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
e120: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
e130: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
e140: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
e150: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e160: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
e170: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
e180: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e190: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
e1a0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
e1b0: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
e1c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
e1d0: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
e1e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e1f0: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
e200: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
e210: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
e220: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
e230: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e240: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
e250: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
e260: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
e270: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
e280: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
e290: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
e2a0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
e2b0: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
e2c0: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
e2d0: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
e2e0: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
e2f0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
e300: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
e310: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
e320: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
e330: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
e340: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
e350: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e360: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e370: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e380: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
e390: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
e3a0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
e3b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e3c0: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
e3d0: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
e3e0: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
e3f0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
e400: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
e410: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
e420: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
e430: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
e440: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
e450: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
e460: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
e470: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e480: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
e490: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
e4a0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
e4b0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
e4c0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
e4d0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
e4e0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
e4f0: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
e500: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
e510: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
e520: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
e530: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
e540: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e550: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
e560: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
e570: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
e580: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
e590: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
e5a0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
e5b0: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
e5c0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
e5d0: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
e5e0: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
e5f0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
e600: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
e610: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
e620: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e630: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
e640: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
e650: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e660: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
e670: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
e680: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
e690: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e6a0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
e6b0: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
e6c0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e6d0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
e6e0: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
e6f0: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
e700: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
e710: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
e720: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
e730: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e740: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
e750: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
e760: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
e770: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
e780: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
e790: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
e7a0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
e7b0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
e7c0: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
e7d0: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
e7e0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
e7f0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
e800: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
e810: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
e820: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
e830: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
e840: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
e850: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e860: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
e870: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
e880: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
e890: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
e8a0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
e8b0: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
e8c0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
e8d0: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
e8e0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
e8f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e900: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
e910: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
e920: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
e930: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
e940: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
e950: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
e960: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
e970: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
e980: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
e990: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
e9a0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
e9b0: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
e9c0: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
e9d0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
e9e0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
e9f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
ea00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
ea10: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
ea20: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
ea30: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ea40: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
ea50: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
ea60: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
ea70: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
ea80: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
ea90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eaa0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
eab0: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
eac0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ead0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
eae0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
eaf0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
eb00: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
eb10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
eb20: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
eb30: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
eb40: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
eb50: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
eb60: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
eb70: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
eb80: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
eb90: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
eba0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
ebb0: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
ebc0: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
ebd0: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
ebe0: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
ebf0: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
ec00: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
ec10: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
ec20: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
ec30: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
ec40: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
ec50: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
ec60: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
ec70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
ec80: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
ec90: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
eca0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
ecb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
ecc0: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
ecd0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
ece0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
ecf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ed00: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
ed10: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
ed20: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
ed30: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
ed40: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
ed50: 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  re..*/.SQLITE_AP
ed60: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  I int sqlite3_in
ed70: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
ed80: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
ed90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
eda0: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
edb0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
edc0: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
edd0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
ede0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
edf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ee00: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
ee10: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ee20: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
ee30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
ee40: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
ee50: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
ee60: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
ee70: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
ee80: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
ee90: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
eea0: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
eeb0: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
eec0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
eed0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
eee0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
eef0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
ef00: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
ef10: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
ef20: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
ef30: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
ef40: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
ef50: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
ef60: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
ef70: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
ef80: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
ef90: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
efa0: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
efb0: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
efc0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
efd0: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
efe0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
eff0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
f000: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
f010: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
f020: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
f030: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
f040: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
f050: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
f060: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
f070: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
f080: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
f090: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
f0a0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
f0b0: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
f0c0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f0d0: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
f0e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f0f0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
f100: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f110: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
f120: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
f130: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
f140: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
f150: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
f160: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
f170: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
f180: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
f190: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
f1a0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
f1b0: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
f1c0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
f1d0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f1e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
f1f0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
f200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f210: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
f220: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f230: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
f240: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
f250: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
f260: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
f270: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
f280: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
f290: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f2a0: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
f2b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
f2c0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f2d0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
f2e0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
f2f0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
f300: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
f310: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
f320: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
f330: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
f340: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
f350: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
f360: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
f370: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
f380: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
f390: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
f3a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
f3b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
f3c0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
f3d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
f3e0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
f3f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
f400: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f410: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
f420: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
f430: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
f440: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
f450: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
f460: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
f470: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
f480: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
f490: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
f4a0: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
f4b0: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
f4c0: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
f4d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f4e0: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
f4f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f500: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
f510: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
f520: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f530: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
f540: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
f550: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
f560: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
f570: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
f580: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
f590: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
f5a0: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
f5b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f5c0: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
f5d0: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
f5e0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
f5f0: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
f600: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
f610: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
f620: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
f630: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
f640: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
f650: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
f660: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
f670: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
f680: 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
f690: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
f6a0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
f6b0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
f6c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f6d0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
f6e0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
f6f0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
f700: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
f710: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
f720: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
f730: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
f740: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
f750: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
f760: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
f770: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
f780: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
f790: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
f7a0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
f7b0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
f7c0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
f7d0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
f7e0: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
f7f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
f800: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
f810: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
f820: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f830: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
f840: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
f850: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
f860: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
f870: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
f880: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
f890: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
f8a0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
f8b0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
f8c0: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
f8d0: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
f8e0: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
f8f0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
f900: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
f910: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
f920: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
f930: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
f940: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
f950: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
f960: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
f970: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
f980: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
f990: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
f9a0: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
f9b0: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
f9c0: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
f9d0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
f9e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
f9f0: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
fa00: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
fa10: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
fa20: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
fa30: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
fa40: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
fa50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
fa60: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
fa70: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
fa80: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
fa90: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
faa0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
fab0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
fac0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
fad0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
fae0: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
faf0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
fb00: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
fb10: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
fb20: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
fb30: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
fb40: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
fb50: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
fb60: 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
fb70: 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
fb80: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
fb90: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
fba0: 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
fbb0: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
fbc0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
fbd0: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
fbe0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
fbf0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
fc00: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
fc10: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
fc20: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
fc30: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
fc40: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
fc50: 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
fc60: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
fc70: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
fc80: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
fc90: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
fca0: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
fcb0: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
fcc0: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
fcd0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
fce0: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
fcf0: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
fd00: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
fd10: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
fd20: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
fd30: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
fd40: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
fd50: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
fd60: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
fd70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
fd80: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
fd90: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
fda0: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
fdb0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
fdc0: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
fdd0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
fde0: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
fdf0: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
fe00: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
fe10: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
fe20: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
fe30: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
fe40: 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
fe50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe60: 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
fe70: 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
fe80: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
fe90: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
fea0: 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
feb0: 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
fec0: 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
fed0: 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
fee0: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
fef0: 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
ff00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
ff10: 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
ff20: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
ff30: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
ff40: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
ff50: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
ff60: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
ff70: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
ff80: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
ff90: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
ffa0: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
ffb0: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
ffc0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
ffd0: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
ffe0: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
fff0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10000 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10010 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10020 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10030 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10040 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10050 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10060 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10070 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10080 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10090 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
100a0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
100b0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
100c0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
100d0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
100e0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
100f0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10100 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
10110 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
10120 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
10130 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
10140 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10150 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
10160 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
10170 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
10180 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
10190 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
101a0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
101b0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
101c0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
101d0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
101e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
101f0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
10200 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10210 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
10220 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
10230 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
10240 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
10250 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
10260 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
10270 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
10280 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10290 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
102a0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
102b0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
102c0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
102d0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
102e0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
102f0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
10300 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
10310 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
10320 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
10330 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
10340 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
10350 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
10360 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
10370 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
10380 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
10390 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
103a0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
103b0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
103c0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
103d0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
103e0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
103f0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
10400 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
10410 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
10420 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
10430 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
10440 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
10450 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
10460 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
10470 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10480 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
10490 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
104a0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
104b0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
104c0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
104d0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
104e0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
104f0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
10500 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
10510 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
10520 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
10530 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
10540 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
10550 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
10560 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
10570 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
10580 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
10590 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
105a0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
105b0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
105c0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
105d0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
105e0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
105f0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
10600 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
10610 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
10620 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
10630 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
10640 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
10650 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
10660 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
10670 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10680 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
10690 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
106a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
106b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
106c0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
106d0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
106e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106f0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
10700 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
10710 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
10720 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
10730 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10740 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10750 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10760 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10770 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10780 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10790 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
107a0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
107b0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
107c0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
107d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
107e0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
107f0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
10800 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
10810 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
10820 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
10830 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10840 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
10850 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
10860 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10870 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
10880 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10890 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
108a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
108b0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
108c0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
108d0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
108e0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
108f0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
10900 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
10910 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10920 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
10930 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
10940 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
10950 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
10960 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
10970 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
10980 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
10990 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
109a0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
109b0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
109c0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
109d0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
109e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
109f0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
10a00 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
10a10 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
10a20 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
10a30 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
10a40 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
10a50 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
10a60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
10a70 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
10a80 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
10a90 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
10aa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10ab0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
10ac0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ad0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
10af0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
10b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
10b10 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
10b20 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
10b30 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
10b40 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
10b50 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
10b60 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
10b70 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
10b80 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
10b90 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
10ba0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
10bb0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
10bc0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
10bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10be0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
10bf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
10c00 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
10c10 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
10c20 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
10c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
10c40 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
10c50 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
10c60 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
10c70 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
10c80 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
10c90 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
10ca0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
10cb0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
10cc0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
10cd0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
10ce0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
10cf0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
10d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10d10 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
10d20 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
10d30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
10d40 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
10d50 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
10d60 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
10d70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
10d80 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
10d90 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
10da0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
10db0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
10dc0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
10dd0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10de0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
10df0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
10e00 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
10e10 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
10e20 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
10e30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10e40 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
10e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10e60 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
10e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10e80 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
10e90 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10ea0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
10eb0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
10ec0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
10ed0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
10ee0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
10ef0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
10f00 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
10f10 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
10f20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
10f30 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
10f40 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
10f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10f60 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
10f70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
10f80 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
10f90 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
10fa0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
10fb0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10fc0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
10fd0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
10fe0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
10ff0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11000 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11010 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11030 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11040 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11050 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11060 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11070 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11090 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
110a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
110b0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
110c0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
110d0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
110e0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
110f0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11100 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11110 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11120 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11130 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11140 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11150 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11160 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
11170 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
11180 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11190 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
111a0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
111b0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
111c0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
111d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
111e0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
111f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11200 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11210 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11220 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11230 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
11240 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11250 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11260 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11270 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11280 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11290 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
112a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
112b0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
112c0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
112d0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
112e0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
112f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11300 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11310 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
11320 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11330 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11340 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11350 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
11360 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
11370 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
11380 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
11390 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
113a0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
113b0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
113c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
113d0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
113e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
113f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
11400 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
11410 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11420 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
11430 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11440 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11450 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
11460 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
11470 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
11480 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11490 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
114a0 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
114b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
114c0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
114d0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
114e0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
114f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11500 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
11510 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
11520 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
11530 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
11540 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11550 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
11560 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
11570 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
11580 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11590 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
115a0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
115b0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
115c0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
115d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
115e0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
115f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11600 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
11610 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
11620 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
11630 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
11640 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
11650 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
11660 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
11670 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
11680 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
11690 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
116a0 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
116b0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
116c0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
116d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
116e0 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
116f0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
11700 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
11710 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
11720 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
11730 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11740 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
11750 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
11760 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
11770 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11780 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
11790 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
117a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
117b0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
117c0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
117d0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
117e0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
117f0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
11800 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
11810 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
11820 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
11830 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
11840 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
11850 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
11860 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
11870 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
11880 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
11890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
118a0 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
118b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
118c0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
118d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
118e0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
118f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
11900 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
11910 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
11920 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
11930 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
11940 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
11950 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
11960 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
11970 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
11980 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11990 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
119a0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
119b0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
119c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
119d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
119e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
119f0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
11a00 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
11a10 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
11a20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
11a30 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
11a40 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
11a50 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
11a60 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
11a70 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
11a80 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
11a90 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
11aa0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
11ab0 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
11ac0 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
11ad0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
11ae0 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
11af0 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
11b00 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
11b10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
11b20 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
11b30 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
11b40 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
11b50 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
11b60 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
11b70 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
11b80 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
11b90 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
11ba0 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
11bb0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
11bc0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
11bd0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
11be0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11bf0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
11c00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11c10 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
11c20 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
11c30 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
11c40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11c50 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
11c60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c70 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
11c80 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11c90 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11ca0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11cb0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11cc0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11cd0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
11ce0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
11cf0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
11d00 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
11d10 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
11d20 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11d30 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
11d40 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
11d50 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
11d60 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
11d70 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
11d80 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
11d90 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
11da0 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
11db0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
11dc0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
11dd0 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
11de0 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
11df0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
11e00 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
11e10 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
11e20 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
11e30 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
11e40 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
11e50 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
11e60 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
11e70 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
11e80 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
11e90 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
11ea0 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
11eb0 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
11ec0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
11ed0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
11ee0 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
11ef0 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
11f00 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
11f10 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
11f20 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
11f30 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
11f40 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
11f50 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
11f60 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
11f70 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
11f80 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
11f90 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
11fa0 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
11fb0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
11fc0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
11fd0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
11fe0 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
11ff0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12000 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12010 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12020 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12030 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12040 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12050 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12060 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12070 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12080 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12090 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
120a0 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
120b0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
120c0 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
120d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
120e0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
120f0 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12100 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
12110 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12120 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
12130 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
12140 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
12150 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12160 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
12170 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
12180 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12190 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
121a0 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
121b0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
121c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
121d0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
121e0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
121f0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12200 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
12210 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
12220 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
12230 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
12240 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
12250 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
12260 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12270 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
12280 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12290 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
122a0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
122b0 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
122c0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
122d0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
122e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
122f0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
12300 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
12310 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12320 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
12330 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
12340 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
12350 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
12360 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
12370 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
12380 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
12390 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
123a0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
123b0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
123c0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
123d0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
123e0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
123f0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
12400 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
12410 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
12420 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
12430 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
12440 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
12450 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
12460 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
12470 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
12480 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
12490 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
124a0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
124b0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
124c0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
124d0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
124e0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
124f0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
12500 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
12510 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12520 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
12530 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
12540 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
12550 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12560 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
12570 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12580 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
12590 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
125a0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
125b0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
125c0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
125d0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
125e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
125f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
12600 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
12610 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
12620 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12630 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12640 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12650 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
12660 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
12670 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12680 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
12690 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
126a0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
126b0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
126c0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
126d0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
126e0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
126f0 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
12700 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
12710 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
12720 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12730 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
12740 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12750 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12760 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
12770 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
12780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
12790 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
127a0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
127b0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
127c0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
127d0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
127e0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
127f0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12800 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
12810 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
12820 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
12830 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
12840 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
12850 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12860 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
12870 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12880 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
12890 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
128a0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
128b0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
128c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
128d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
128e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
128f0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
12900 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
12910 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12920 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12930 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
12940 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
12950 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12960 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
12970 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
12980 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
12990 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
129a0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
129b0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
129c0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
129d0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
129e0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
129f0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
12a00 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
12a10 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
12a20 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12a30 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12a40 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
12a50 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
12a60 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
12a70 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
12a80 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
12a90 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
12aa0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12ab0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12ac0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12ad0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12ae0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12af0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12b00 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12b10 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12b20 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12b30 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
12b40 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
12b50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
12b60 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12b70 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
12b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12b90 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
12ba0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
12bb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12bd0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
12be0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
12bf0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
12c00 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12c10 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
12c20 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
12c30 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
12c40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c50 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
12c60 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
12c70 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c90 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
12ca0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
12cb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
12cc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
12cd0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
12ce0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
12cf0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
12d00 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
12d10 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
12d20 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
12d30 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12d40 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
12d50 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
12d60 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
12d70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12d80 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
12d90 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
12da0 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
12db0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
12dc0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
12dd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
12de0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
12df0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
12e00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12e10 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
12e20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12e30 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
12e40 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12e50 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12e60 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12e70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12e80 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
12e90 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12ea0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
12eb0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
12ec0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
12ed0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
12ee0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
12ef0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
12f00 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
12f10 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
12f20 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
12f30 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
12f40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
12f50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12f60 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12f70 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
12f80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
12f90 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
12fa0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12fc0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12fd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
12ff0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13000 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13010 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13020 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13030 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13040 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13050 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13060 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13070 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13080 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13090 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
130a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
130b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
130c0 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
130d0 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
130e0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
130f0 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
13100 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
13110 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
13120 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
13130 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
13140 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
13150 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13160 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
13170 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13180 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
13190 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
131a0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
131b0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
131c0 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
131d0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
131e0 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
131f0 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
13200 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
13210 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
13220 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
13230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13240 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
13250 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
13260 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
13270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
13280 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
13290 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
132a0 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
132b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
132c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
132d0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
132e0 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
132f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
13300 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13310 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
13320 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
13330 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
13340 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
13350 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
13360 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
13370 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
13380 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
13390 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
133a0 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
133b0 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
133c0 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
133d0 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
133e0 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
133f0 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
13400 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
13410 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
13420 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
13430 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
13440 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13450 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
13460 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
13470 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
13480 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
13490 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
134a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
134b0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
134c0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
134d0 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
134e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
134f0 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
13500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
13510 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70  .** <dd> This op
13520 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13530 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
13540 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e  type int. If non
13550 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55  -zero, then.** U
13560 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13570 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
13580 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
13590 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  r is zero, then 
135a0 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20  URI handling.** 
135b0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
135c0 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e  bled. If URI han
135d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
135e0 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  y enabled, all f
135f0 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73  ilenames.** pass
13600 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
13610 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
13620 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71  _open_v2()], [sq
13630 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
13640 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
13650 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
13660 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
13670 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
13680 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
13690 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
136a0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
136b0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
136c0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
136d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
136e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
136f0 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62  d. If it is glob
13700 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
13710 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
13720 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
13730 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
13740 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
13750 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13760 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
13770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13780 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c  pened. By defaul
13790 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
137a0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
137b0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
137c0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
137d0 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
137e0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
137f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
13800 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
13810 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
13820 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
13830 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
13840 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13850 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
13860 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68  _SCAN.** <dd> Th
13870 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13880 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
13890 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
138a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
138b0 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69  s.** a boolean i
138c0 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
138d0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
138e0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
138f0 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20   indices for.** 
13900 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13910 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
13920 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65  timizer.  The de
13930 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
13940 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
13950 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
13960 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
13970 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
13980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
13990 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
139a0 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
139b0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
139c0 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
139d0 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
139e0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
139f0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
13a00 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
13a10 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
13a20 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
13a30 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
13a40 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
13a50 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c  lfunction.** mal
13a60 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68  function when th
13a70 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
13a80 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
13a90 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
13aa0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
13ab0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
13ac0 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
13ad0 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
13ae0 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
13af0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
13b00 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
13b10 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
13b20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
13b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13b40 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
13b50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13b60 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
13b70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
13b80 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
13b90 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
13ba0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
13bb0 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
13bc0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
13bd0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
13be0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
13bf0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
13c00 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
13c10 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
13c20 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  o-ops..** </dl>.
13c30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13c40 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
13c50 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
13c60 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
13c70 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
13c80 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
13c90 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
13ca0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
13cb0 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  * SQLITE_ENABLE_
13cc0 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63 65  SQLLOG pre-proce
13cd0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
13ce0 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
13cf0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
13d00 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
13d10 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
13d20 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
13d30 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
13d40 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
13d50 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
13d60 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
13d70 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
13d80 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
13d90 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
13da0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
13db0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
13dc0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
13dd0 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
13de0 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
13df0 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
13e00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
13e10 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
13e20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13e30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
13e40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
13e50 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
13e60 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
13e70 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
13e80 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
13e90 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
13ea0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
13eb0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
13ec0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
13ed0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
13ee0 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
13ef0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
13f00 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
13f10 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
13f20 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
13f30 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
13f40 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
13f50 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
13f60 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
13f70 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
13f80 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
13f90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
13fa0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
13fb0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
13fc0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
13fd0 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 0a  L In this case..
13fe0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
13ff0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14000 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
14010 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
14020 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14030 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
14040 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
14050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14060 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
14070 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
14080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14090 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
140a0 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
140b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
140c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
140d0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
140e0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
140f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
14100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14110 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14120 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
14130 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
14140 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
14150 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14160 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
14170 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
14180 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
14190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
141a0 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
141b0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
141c0 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
141d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
141e0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
141f0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
14200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14210 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
14220 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
14230 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14240 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14250 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14260 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
14270 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
14280 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
14290 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
142a0 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
142b0 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
142c0 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
142d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
142e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
142f0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
14300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14310 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14320 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
14330 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
14340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14350 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
14360 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
14370 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14380 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
14390 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
143a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
143b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
143c0 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
143d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
143e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
143f0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
14400 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14410 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
14420 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14430 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
14440 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
14450 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
14460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14470 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14480 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
14490 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
144a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
144b0 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
144c0 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
144d0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
144e0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
144f0 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
14500 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
14510 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
14520 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
14530 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
14540 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14550 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
14560 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
14570 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14580 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
14590 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
145a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
145b0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
145c0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
145d0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
145e0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
145f0 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
14600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14610 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
14620 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
14630 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
14640 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
14650 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
14660 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
14670 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
14680 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
14690 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
146a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
146b0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
146c0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
146d0 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
146e0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
146f0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
14700 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
14710 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
14720 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
14730 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
14740 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
14750 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
14760 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
14770 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
14780 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
14790 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
147a0 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
147b0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
147c0 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
147d0 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
147e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
147f0 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
14800 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
14810 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14820 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
14830 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
14840 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
14850 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
14860 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
14870 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
14880 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14890 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
148a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
148b0 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
148c0 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
148d0 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
148e0 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
148f0 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
14900 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
14910 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
14920 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
14930 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
14940 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
14950 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
14960 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
14970 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
14980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
14990 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
149a0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
149b0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
149c0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
149d0 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
149e0 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
149f0 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
14a00 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
14a10 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
14a20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
14a30 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
14a40 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
14a50 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
14a60 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
14a70 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14a80 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
14a90 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
14aa0 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
14ab0 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
14ac0 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
14ad0 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
14ae0 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
14af0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
14b00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
14b10 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
14b20 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
14b30 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
14b40 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
14b50 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
14b60 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
14b70 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
14b80 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
14b90 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
14ba0 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
14bb0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
14bc0 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
14bd0 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
14be0 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
14bf0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
14c00 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
14c10 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
14c20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
14c30 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
14c40 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
14c50 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
14c60 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
14c70 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
14c80 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
14c90 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
14ca0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
14cb0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
14cc0 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
14cd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
14ce0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
14cf0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
14d00 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
14d10 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
14d20 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
14d30 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
14d40 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
14d50 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
14d60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14d70 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
14d80 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
14d90 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
14da0 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
14db0 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
14dc0 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
14dd0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
14de0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
14df0 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
14e00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14e10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
14e20 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
14e30 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
14e40 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
14e50 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
14e60 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
14e70 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
14e80 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
14e90 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
14ea0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
14eb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14ec0 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
14ed0 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
14ee0 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
14ef0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
14f00 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
14f10 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
14f20 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
14f30 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
14f40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
14f50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
14f60 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
14f70 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
14f80 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
14f90 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
14fa0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
14fb0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14fc0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
14fd0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
14fe0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
14ff0 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
15000 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
15010 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
15020 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
15030 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
15040 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15050 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
15060 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
15070 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
15080 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
15090 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
150a0 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
150b0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
150c0 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
150d0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
150e0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
150f0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15110 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15120 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
15130 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
15140 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
15150 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
15160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15170 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15180 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
15190 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
151a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
151b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
151c0 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
151d0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
151e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
151f0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
15200 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
15210 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
15220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
15230 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
15240 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
15250 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
15260 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
15270 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
15280 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
15290 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
152a0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
152b0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
152c0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
152d0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
152e0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
152f0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
15300 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
15310 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
15320 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15330 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
15340 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
15350 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
15360 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
15370 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
15380 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
15390 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
153a0 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
153b0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
153c0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
153d0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
153e0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
153f0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
15400 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
15410 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
15420 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
15430 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
15440 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
15450 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
15460 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
15470 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
15480 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
15490 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
154a0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
154b0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
154c0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
154d0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
154e0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
154f0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
15500 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
15510 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
15520 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
15530 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
15540 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
15550 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
15560 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
15570 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
15580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
15590 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
155a0 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
155b0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
155c0 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
155d0 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
155e0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
155f0 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
15600 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
15610 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
15620 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
15630 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15640 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
15650 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
15660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15670 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
15680 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
15690 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
156a0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
156b0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
156c0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
156d0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
156e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
156f0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
15700 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
15710 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
15720 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
15730 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
15740 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
15750 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
15760 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
15770 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
15780 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
15790 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
157a0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
157b0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
157c0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
157d0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
157e0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
157f0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
15800 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
15810 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
15820 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
15830 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
15840 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
15850 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
15860 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
15870 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
15880 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
15890 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
158a0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
158b0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
158c0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
158d0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
158e0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
158f0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
15900 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
15910 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
15920 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
15930 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
15940 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
15950 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
15960 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
15970 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
15980 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
15990 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
159a0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
159b0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
159c0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
159d0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
159e0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
159f0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
15a00 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
15a10 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
15a20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
15a30 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
15a40 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
15a50 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
15a60 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
15a70 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
15a80 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
15a90 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
15aa0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
15ab0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
15ac0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
15ad0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
15ae0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
15af0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
15b00 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
15b10 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
15b20 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
15b30 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
15b40 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
15b50 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
15b60 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
15b70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
15b80 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
15b90 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
15ba0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
15bb0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
15bc0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
15bd0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
15be0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
15bf0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
15c00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
15c10 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
15c20 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
15c30 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
15c40 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
15c50 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
15c60 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
15c70 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
15c80 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
15c90 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
15ca0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
15cb0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
15cc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
15cd0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
15ce0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
15cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
15d00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
15d10 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
15d20 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
15d30 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
15d40 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
15d50 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
15d60 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
15d70 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
15d80 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
15d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15da0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
15db0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15dc0 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
15dd0 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
15de0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
15df0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
15e00 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
15e10 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
15e20 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
15e30 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
15e40 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
15e50 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
15e60 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15e70 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
15e80 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
15e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
15ea0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
15eb0 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
15ec0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
15ed0 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
15ee0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
15ef0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
15f00 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
15f10 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
15f20 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
15f30 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
15f40 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
15f50 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
15f60 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
15f70 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
15f80 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
15f90 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
15fa0 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
15fb0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
15fc0 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
15fd0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
15fe0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
15ff0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
16000 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
16010 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
16020 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
16030 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
16040 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
16050 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
16060 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
16070 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
16080 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
16090 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
160a0 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
160b0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
160c0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
160d0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
160e0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
160f0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
16100 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
16110 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
16120 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
16130 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
16140 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
16150 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
16160 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
16170 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
16180 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
16190 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
161a0 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
161b0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
161c0 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
161d0 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
161e0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
161f0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
16200 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
16210 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
16220 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
16230 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
16240 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
16250 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
16260 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
16270 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
16280 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
16290 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
162a0 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
162b0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
162c0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
162d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
162e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
162f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
16300 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
16310 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
16320 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16330 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
16340 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
16350 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
16360 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
16370 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
16380 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
16390 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
163a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
163b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
163c0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
163d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
163e0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
163f0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
16400 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
16410 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
16420 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
16430 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
16440 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
16450 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
16460 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
16470 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
16480 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
16490 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
164a0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
164b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
164c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
164d0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
164e0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
164f0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
16500 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
16510 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
16520 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
16530 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
16540 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
16550 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
16560 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
16570 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
16580 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
16590 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
165a0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
165b0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
165c0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
165d0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
165e0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
165f0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
16600 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
16610 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
16620 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
16630 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
16640 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
16650 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
16660 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
16670 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
16680 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
16690 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
166a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
166b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
166c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
166d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
166e0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
166f0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
16700 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16710 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16720 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
16730 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
16740 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
16750 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
16760 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
16770 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16780 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
16790 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
167a0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
167b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
167c0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
167d0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
167e0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
167f0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
16800 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
16810 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
16820 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16830 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
16840 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
16850 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16860 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
16870 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
16880 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
16890 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
168a0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
168b0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
168c0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
168d0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
168e0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
168f0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
16900 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
16910 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
16920 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
16930 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
16940 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
16950 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
16960 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
16970 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
16980 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
16990 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
169a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
169b0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
169c0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
169d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
169e0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
169f0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
16a00 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
16a10 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
16a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
16a30 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
16a40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
16a50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
16a60 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
16a70 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
16a80 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
16a90 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
16aa0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
16ab0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
16ac0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
16ad0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
16ae0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
16af0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
16b00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16b10 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
16b20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16b30 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
16b40 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
16b50 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
16b60 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
16b70 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
16b80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
16b90 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
16ba0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
16bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16bc0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
16bd0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
16be0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
16bf0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
16c00 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
16c10 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
16c20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
16c30 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
16c40 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
16c50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
16c60 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
16c70 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
16c80 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
16c90 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
16ca0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
16cb0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
16cc0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
16cd0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
16ce0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
16cf0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
16d00 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
16d10 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
16d20 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
16d30 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
16d40 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
16d50 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
16d60 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
16d70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
16d80 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
16d90 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
16da0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
16db0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
16dc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
16dd0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
16de0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
16df0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16e00 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
16e10 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
16e20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
16e30 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
16e40 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
16e50 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
16e60 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
16e70 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
16e80 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
16e90 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
16ea0 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
16eb0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
16ec0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
16ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
16ee0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
16ef0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
16f00 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
16f10 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
16f20 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
16f30 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
16f40 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
16f50 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
16f60 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
16f70 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
16f80 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
16f90 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
16fa0 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
16fb0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
16fc0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
16fd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16fe0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
16ff0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
17000 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
17010 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
17020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17030 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
17040 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
17050 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
17060 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
17070 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
17080 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
17090 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
170a0 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
170b0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
170c0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
170d0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
170e0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
170f0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
17100 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
17110 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17120 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
17130 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
17140 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17150 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17160 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
17170 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
17180 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
17190 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
171a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
171b0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
171c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
171d0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
171e0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
171f0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
17200 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
17210 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
17220 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
17230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
17240 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
17250 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
17260 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17270 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
17280 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
17290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
172a0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
172b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
172c0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
172d0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
172e0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
172f0 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ppen..*/.SQLITE_
17300 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
17310 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
17320 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17330 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
17340 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
17350 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
17360 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
17370 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
17380 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
17390 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
173a0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
173b0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
173c0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
173d0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
173e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
173f0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
17400 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
17410 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
17420 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
17430 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
17440 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
17450 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17460 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
17470 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
17480 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
17490 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
174a0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
174b0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
174c0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
174d0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
174e0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
174f0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
17500 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
17510 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
17520 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
17530 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
17540 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
17550 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
17560 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
17570 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
17580 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
17590 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
175a0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
175b0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
175c0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
175d0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
175e0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
175f0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
17600 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
17610 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
17620 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
17630 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
17640 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
17650 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
17660 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
17670 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
17680 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
17690 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
176a0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
176b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
176c0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
176d0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
176e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
176f0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
17700 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
17710 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
17720 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
17730 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
17740 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
17750 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
17760 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
17770 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
17780 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
17790 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
177a0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
177b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
177c0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
177d0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
177e0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
177f0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
17800 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
17810 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
17820 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
17830 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
17840 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
17850 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
17860 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
17870 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
17880 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
17890 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
178a0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
178b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
178c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
178d0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
178e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
178f0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
17900 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
17910 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
17920 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
17930 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
17940 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
17950 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
17960 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
17970 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
17980 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
17990 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
179a0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
179b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
179c0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
179d0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
179e0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
179f0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
17a00 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
17a10 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
17a20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
17a30 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
17a40 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
17a50 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
17a60 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
17a70 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
17a80 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
17a90 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
17aa0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
17ab0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
17ac0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
17ad0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
17ae0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
17af0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
17b00 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
17b10 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
17b20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
17b30 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
17b40 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
17b50 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
17b60 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
17b70 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
17b80 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
17b90 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
17ba0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
17bb0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17bc0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
17bd0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
17be0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
17bf0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
17c00 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
17c10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
17c20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
17c30 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
17c40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
17c50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
17c60 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
17c70 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
17c80 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
17c90 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
17ca0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
17cb0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
17cc0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
17cd0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17ce0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
17cf0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
17d00 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
17d10 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
17d20 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
17d30 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17d40 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
17d50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
17d60 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
17d70 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
17d80 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
17d90 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
17da0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
17db0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
17dc0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
17dd0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
17de0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
17df0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
17e00 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
17e10 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
17e20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
17e30 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
17e40 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
17e50 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17e60 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
17e70 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
17e80 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
17e90 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
17ea0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
17eb0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
17ec0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
17ed0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
17ee0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
17ef0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
17f00 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
17f10 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
17f20 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
17f30 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
17f40 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
17f50 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
17f60 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
17f70 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
17f80 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
17f90 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
17fa0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
17fb0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
17fc0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
17fd0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
17fe0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
17ff0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
18000 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
18010 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
18020 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
18030 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
18040 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
18050 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
18060 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
18070 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
18080 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
18090 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
180a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
180b0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
180c0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
180d0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
180e0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
180f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
18100 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
18110 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
18120 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
18130 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
18140 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
18150 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
18160 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
18170 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
18180 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
18190 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
181a0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
181b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
181c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
181d0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
181e0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
181f0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
18200 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
18210 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
18220 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
18230 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
18240 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
18250 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
18260 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
18270 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
18280 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
18290 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
182a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
182b0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
182c0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
182d0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
182e0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
182f0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
18300 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
18310 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18320 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
18330 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
18340 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
18350 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
18360 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
18370 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
18380 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
18390 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
183a0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
183b0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
183c0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
183d0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
183e0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
183f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
18400 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
18410 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
18420 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
18430 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
18440 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
18450 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
18460 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
18470 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
18480 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
18490 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
184a0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
184b0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
184c0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
184d0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
184e0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
184f0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
18500 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
18510 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
18520 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
18530 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
18540 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
18550 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
18560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18570 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
18580 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
18590 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
185a0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
185b0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
185c0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
185d0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
185e0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
185f0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
18600 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
18610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
18620 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
18630 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
18640 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
18650 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
18660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
18670 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
18680 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
18690 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
186a0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
186b0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
186c0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
186d0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
186e0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
186f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
18700 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
18710 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
18720 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
18730 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
18740 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
18750 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
18760 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
18770 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
18780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18790 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
187a0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
187b0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
187c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
187d0 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
187e0 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
187f0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
18800 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
18810 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
18820 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
18830 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
18840 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
18850 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
18860 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
18870 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
18880 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
18890 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
188a0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
188b0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
188c0 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
188d0 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
188e0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
188f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18900 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
18910 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18920 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18930 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
18940 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
18950 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
18960 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
18970 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
18980 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
18990 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
189a0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
189b0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
189c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
189d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
189e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
189f0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
18a00 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
18a10 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
18a20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
18a30 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
18a40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
18a50 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
18a60 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
18a70 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
18a80 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
18a90 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
18aa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
18ab0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
18ac0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
18ad0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
18ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
18af0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
18b00 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
18b10 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
18b20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
18b30 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
18b40 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
18b50 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
18b60 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
18b70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
18b80 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
18b90 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
18ba0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
18bb0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
18bc0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
18bd0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
18be0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
18bf0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
18c00 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
18c10 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
18c20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
18c30 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
18c40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
18c50 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
18c60 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
18c70 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
18c80 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
18c90 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
18ca0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
18cb0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
18cc0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
18cd0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
18ce0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
18cf0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
18d00 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
18d10 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
18d20 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
18d30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
18d40 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
18d50 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
18d60 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
18d70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
18d80 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
18d90 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
18da0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
18db0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
18dc0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
18dd0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
18de0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
18df0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
18e00 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
18e10 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
18e20 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
18e30 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
18e40 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
18e50 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
18e60 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
18e70 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
18e80 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
18e90 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
18ea0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
18eb0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
18ec0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
18ed0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
18ee0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
18ef0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
18f00 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
18f10 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
18f20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
18f30 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
18f40 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
18f50 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
18f60 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
18f70 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
18f80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
18f90 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
18fa0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
18fb0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
18fc0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
18fd0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
18fe0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
18ff0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
19000 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
19010 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
19020 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19030 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19040 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
19050 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
19060 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19070 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
19080 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
19090 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
190a0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
190b0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
190c0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
190d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
190e0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
190f0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
19100 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
19110 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
19120 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
19130 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
19140 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
19150 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
19160 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
19170 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
19180 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
19190 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
191a0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
191b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
191c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
191d0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
191e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
191f0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
19200 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19210 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
19220 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
19230 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
19240 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
19250 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19260 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
19270 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19280 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
19290 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
192a0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
192b0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
192c0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
192d0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
192e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
192f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19300 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
19310 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
19320 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
19330 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
19340 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
19350 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
19360 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
19370 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
19380 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
19390 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
193a0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
193b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
193c0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
193d0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
193e0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
193f0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
19400 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
19410 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
19420 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
19430 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
19440 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
19450 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
19460 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
19470 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
19480 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
19490 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
194a0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
194b0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
194c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
194d0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
194e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
194f0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
19500 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
19510 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
19520 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
19530 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
19540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
19550 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
19560 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
19570 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
19580 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
19590 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
195a0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
195b0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
195c0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
195d0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
195e0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
195f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
19600 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
19610 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
19620 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
19630 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
19640 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
19650 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
19660 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
19670 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
19680 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
19690 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
196a0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
196b0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
196c0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
196d0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
196e0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
196f0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
19700 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
19710 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
19720 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
19730 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
19740 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
19750 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
19760 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
19770 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
19780 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
19790 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
197a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
197b0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
197c0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
197d0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
197e0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
197f0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
19800 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
19810 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
19820 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
19830 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
19840 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
19850 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
19860 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
19870 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
19880 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
19890 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
198a0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
198b0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
198c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
198d0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
198e0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
198f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
19900 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
19910 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
19920 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
19930 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
19940 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
19950 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
19960 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
19970 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
19980 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
19990 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
199a0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
199b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
199c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
199d0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
199e0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
199f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
19a00 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
19a10 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
19a20 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
19a30 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
19a40 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
19a50 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
19a60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
19a70 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
19a80 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
19a90 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
19aa0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
19ab0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
19ac0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
19ad0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
19ae0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
19af0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
19b00 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
19b10 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
19b20 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
19b30 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
19b40 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
19b50 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
19b60 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
19b70 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
19b80 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
19b90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19ba0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
19bb0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
19bc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
19bd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
19be0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
19bf0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
19c00 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
19c10 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
19c20 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
19c30 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
19c40 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
19c50 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
19c60 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
19c70 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19c80 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
19c90 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
19ca0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
19cb0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
19cc0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
19cd0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
19ce0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
19cf0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
19d00 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
19d10 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
19d20 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
19d30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
19d40 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
19d50 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
19d60 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
19d70 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
19d80 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
19d90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
19da0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19db0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
19dc0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
19dd0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
19de0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
19df0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
19e00 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
19e10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19e20 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
19e30 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
19e40 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
19e50 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
19e60 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
19e70 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
19e80 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
19e90 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
19ea0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
19eb0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
19ec0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
19ed0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
19ee0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
19ef0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
19f00 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
19f10 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
19f20 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
19f30 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
19f40 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
19f50 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
19f60 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
19f70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
19f80 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
19f90 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
19fa0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
19fb0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
19fc0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
19fd0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
19fe0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
19ff0 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1a000 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1a010 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1a020 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1a030 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1a040 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1a050 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1a060 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1a070 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1a080 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1a090 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1a0a0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1a0b0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1a0c0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1a0d0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1a0e0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1a0f0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1a100 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1a110 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1a120 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1a130 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1a140 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1a150 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1a160 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1a170 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1a180 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1a190 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1a1a0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1a1b0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1a1c0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1a1d0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1a1e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a1f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1a200 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1a210 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1a220 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a230 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1a240 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1a250 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1a260 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1a270 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a280 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a290 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1a2a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1a2b0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1a2c0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1a2d0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1a2e0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1a2f0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1a300 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1a310 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1a320 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a330 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1a340 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1a350 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1a360 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1a370 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1a380 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1a390 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1a3a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1a3b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a3c0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1a3d0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1a3e0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1a3f0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1a400 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a410 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1a420 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1a430 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1a440 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1a450 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1a460 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1a470 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a480 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1a490 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1a4a0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1a4b0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1a4c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1a4d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1a4e0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1a4f0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1a500 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1a510 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1a520 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1a530 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1a540 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1a550 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1a560 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1a570 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1a580 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1a590 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1a5a0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1a5b0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1a5c0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1a5d0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1a5e0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1a5f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1a600 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1a610 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1a620 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1a630 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1a640 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1a650 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1a660 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1a670 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1a680 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1a690 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1a6a0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1a6b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1a6c0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1a6d0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1a6e0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1a6f0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1a700 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1a710 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1a720 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1a730 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a740 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1a750 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1a760 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1a770 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1a780 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1a790 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1a7a0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1a7b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1a7c0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1a7d0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1a7e0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1a7f0 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1a800 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1a810 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1a820 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1a830 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1a840 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1a850 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1a860 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1a870 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1a880 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1a890 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1a8a0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1a8b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1a8c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1a8d0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1a8e0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49  , va_list);.SQLI
1a8f0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1a900 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1a910 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1a920 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54  ar*, ...);.SQLIT
1a930 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1a940 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1a950 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1a960 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1a970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a980 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1a990 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1a9a0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1a9b0 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1a9c0 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1a9d0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1a9e0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1a9f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1aa00 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1aa10 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1aa20 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1aa30 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1aa40 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1aa50 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1aa60 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1aa70 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1aa80 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1aa90 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1aaa0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1aab0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aac0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1aad0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1aae0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1aaf0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1ab00 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1ab10 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1ab20 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1ab30 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1ab40 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1ab50 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1ab60 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1ab70 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1ab80 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1ab90 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1aba0 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1abb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1abc0 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1abd0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1abe0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1abf0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1ac00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
1ac10 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1ac20 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1ac30 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1ac40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ac50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1ac60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1ac70 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1ac80 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1ac90 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1aca0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1acb0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1acc0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1acd0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1ace0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1acf0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1ad00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1ad10 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1ad20 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1ad30 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1ad40 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1ad50 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1ad60 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1ad70 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1ad80 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1ad90 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1ada0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1adb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1adc0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1add0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1ade0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1adf0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1ae00 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1ae10 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1ae20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1ae30 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1ae40 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1ae50 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1ae60 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1ae70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1ae80 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1ae90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1aea0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1aeb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
1aec0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1aed0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1aee0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1aef0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
1af00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
1af10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
1af20 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1af30 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
1af40 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
1af50 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
1af60 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1af70 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
1af80 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1af90 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1afa0 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
1afb0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1afc0 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1afd0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1afe0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1aff0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
1b000 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
1b010 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b020 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b030 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
1b040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b050 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1b060 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1b070 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1b080 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1b090 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1b0a0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1b0b0 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
1b0c0 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
1b0d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b0e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1b0f0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
1b100 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
1b110 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1b120 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1b130 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1b140 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1b150 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
1b160 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
1b170 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1b180 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1b190 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1b1a0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1b1b0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1b1c0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1b1d0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1b1e0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1b1f0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1b200 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1b210 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1b220 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
1b230 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
1b240 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
1b250 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1b260 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
1b270 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1b280 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
1b290 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b2a0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1b2b0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1b2c0 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
1b2d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1b2e0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
1b2f0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
1b300 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
1b310 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
1b320 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
1b330 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
1b340 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
1b350 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
1b360 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
1b370 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
1b380 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
1b390 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
1b3a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
1b3b0 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
1b3c0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
1b3d0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
1b3e0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
1b3f0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
1b400 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
1b410 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
1b420 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
1b430 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
1b440 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
1b450 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
1b460 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1b470 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
1b480 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
1b490 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
1b4a0 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
1b4b0 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
1b4c0 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
1b4d0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
1b4e0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1b4f0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
1b500 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
1b510 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
1b520 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1b530 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1b540 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1b550 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1b560 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1b570 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1b580 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1b590 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1b5a0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1b5b0 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1b5c0 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1b5d0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1b5e0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1b5f0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1b600 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1b610 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1b620 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1b630 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1b640 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1b650 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b660 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1b670 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1b680 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1b690 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1b6a0 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1b6b0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1b6c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1b6d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1b6e0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1b6f0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1b700 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1b710 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1b720 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1b730 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1b740 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1b750 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1b760 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1b770 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1b780 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1b790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b7a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1b7b0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1b7c0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c  malloc(int);.SQL
1b7d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
1b7e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1b7f0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
1b800 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1b810 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1b820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b830 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1b840 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1b850 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1b860 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1b870 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1b880 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1b890 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1b8a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1b8b0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1b8c0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1b8d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1b8e0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1b8f0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1b900 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b910 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1b920 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1b930 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b940 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b950 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1b960 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1b970 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1b980 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1b990 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1b9a0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1b9b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1b9c0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1b9d0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1b9e0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1b9f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ba00 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1ba10 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1ba20 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1ba30 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1ba40 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1ba50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ba60 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ba80 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1ba90 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1baa0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1bab0 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1bac0 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1bad0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1bae0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1baf0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1bb00 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1bb10 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1bb20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1bb30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1bb40 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1bb50 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1bb60 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1bb70 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1bb80 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1bb90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1bba0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1bbb0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1bbc0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1bbd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1bbe0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1bbf0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1bc00 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1bc10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bc20 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1bc30 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1bc40 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1bc50 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49  e reset..*/.SQLI
1bc60 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1bc70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1bc80 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1bc90 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1bca0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1bcb0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1bcc0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1bcd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bce0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1bcf0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1bd00 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1bd10 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1bd20 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1bd30 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1bd40 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1bd50 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1bd60 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1bd70 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1bd80 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1bd90 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1bda0 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1bdb0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1bdc0 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1bdd0 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1bde0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1bdf0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1be00 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1be10 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1be20 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1be30 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1be40 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1be50 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1be60 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1be70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1be80 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1be90 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1bea0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1beb0 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1bec0 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
1bed0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
1bee0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
1bef0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
1bf00 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
1bf10 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
1bf20 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1bf30 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1bf40 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
1bf50 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1bf60 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1bf70 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1bf80 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1bf90 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
1bfa0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
1bfb0 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
1bfc0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1bfd0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1bfe0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1bff0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1c000 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1c010 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1c020 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1c030 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
1c040 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
1c050 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
1c060 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
1c070 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
1c080 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
1c090 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c0a0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
1c0b0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
1c0c0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
1c0d0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1c0e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c0f0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
1c100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1c110 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
1c120 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1c130 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
1c140 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
1c150 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
1c160 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
1c170 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1c180 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
1c190 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
1c1a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c1b0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
1c1c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c1d0 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
1c1e0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
1c1f0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
1c200 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
1c210 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
1c220 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
1c230 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
1c240 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
1c250 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1c260 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
1c270 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
1c280 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
1c290 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
1c2a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
1c2b0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
1c2c0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
1c2d0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
1c2e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
1c2f0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
1c300 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
1c310 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
1c320 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1c330 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
1c340 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
1c350 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
1c360 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
1c370 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1c380 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
1c390 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
1c3a0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
1c3b0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
1c3c0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
1c3d0 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1c3e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
1c3f0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
1c400 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
1c410 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
1c420 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1c430 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1c440 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1c450 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1c460 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1c470 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1c480 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
1c490 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c4a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
1c4b0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
1c4c0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
1c4d0 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
1c4e0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1c4f0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1c500 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
1c510 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c520 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1c530 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1c540 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
1c550 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1c560 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1c570 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
1c580 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
1c590 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
1c5a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1c5b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
1c5c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c5d0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1c5e0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
1c5f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c600 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
1c610 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
1c620 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
1c630 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
1c640 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1c650 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
1c660 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
1c670 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
1c680 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
1c690 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1c6a0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1c6b0 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
1c6c0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
1c6d0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
1c6e0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
1c6f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1c700 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
1c710 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
1c720 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1c730 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1c740 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1c750 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1c760 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1c770 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
1c780 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c790 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
1c7a0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
1c7b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c7c0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
1c7d0 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
1c7e0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
1c7f0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
1c800 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1c810 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1c820 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
1c830 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
1c840 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
1c850 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
1c860 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
1c870 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
1c880 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
1c890 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
1c8a0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
1c8b0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
1c8c0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
1c8d0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1c8e0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
1c8f0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
1c900 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
1c910 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1c920 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
1c930 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
1c940 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
1c950 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
1c960 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
1c970 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
1c980 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
1c990 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
1c9a0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
1c9b0 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
1c9c0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1c9d0 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
1c9e0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
1c9f0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
1ca00 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
1ca10 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
1ca20 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
1ca30 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
1ca40 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
1ca50 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
1ca60 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
1ca70 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
1ca80 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
1ca90 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
1caa0 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
1cab0 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
1cac0 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
1cad0 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
1cae0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
1caf0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
1cb00 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
1cb10 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
1cb20 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
1cb30 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
1cb40 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
1cb50 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
1cb60 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
1cb70 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
1cb80 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
1cb90 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
1cba0 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
1cbb0 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
1cbc0 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
1cbd0 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
1cbe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1cbf0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
1cc00 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
1cc10 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
1cc20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1cc30 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
1cc40 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
1cc50 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
1cc60 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
1cc70 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
1cc80 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
1cc90 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
1cca0 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
1ccb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1ccc0 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
1ccd0 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
1cce0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
1ccf0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
1cd00 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
1cd10 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
1cd20 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
1cd30 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
1cd40 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
1cd50 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
1cd60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd70 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
1cd80 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
1cd90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1cda0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
1cdb0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
1cdc0 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
1cdd0 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
1cde0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
1cdf0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
1ce00 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
1ce10 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
1ce20 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
1ce30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1ce40 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1ce50 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1ce60 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1ce70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ce80 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1ce90 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
1cea0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
1ceb0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1cec0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ced0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cee0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1cef0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1cf00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf10 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1cf20 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1cf30 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1cf40 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
1cf50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cf60 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
1cf70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1cf80 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
1cf90 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
1cfa0 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
1cfb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cfc0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
1cfd0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
1cfe0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
1cff0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
1d000 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1d010 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
1d020 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
1d030 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
1d040 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
1d050 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1d060 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
1d070 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d080 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1d090 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
1d0a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1d0b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1d0c0 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
1d0d0 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
1d0e0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
1d0f0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
1d100 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
1d110 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
1d120 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
1d130 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
1d140 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
1d150 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
1d160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d170 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
1d180 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
1d190 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
1d1a0 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
1d1b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65  I int sqlite3_se
1d1c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20  t_authorizer(.  
1d1d0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20  sqlite3*,.  int 
1d1e0 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69  (*xAuth)(void*,i
1d1f0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  nt,const char*,c
1d200 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1d210 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1d220 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73  r*),.  void *pUs
1d230 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  erData.);../*.**
1d240 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1d250 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64  rizer Return Cod
1d260 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1d270 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1d280 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1d290 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1d2a0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
1d2b0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
1d2c0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
1d2d0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
1d2e0 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
1d2f0 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
1d300 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
1d310 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
1d320 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
1d330 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
1d340 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1d350 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
1d360 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
1d370 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1d380 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e  rmation..**.** N
1d390 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f  ote that SQLITE_
1d3a0 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75  IGNORE is also u
1d3b0 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45  sed as a [SQLITE
1d3c0 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75  _ROLLBACK | retu
1d3d0 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d  rn code].** from
1d3e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1d3f0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1d400 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1d410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1d420 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1d430 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1d440 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1d450 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1d460 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1d470 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1d480 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1d490 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1d4a0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1d4b0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1d4c0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1d4d0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1d4e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d4f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1d500 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1d510 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1d520 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1d530 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1d540 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1d550 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1d560 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1d570 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1d580 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1d590 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1d5a0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1d5b0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1d5c0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1d5d0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1d5e0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1d5f0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1d600 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1d610 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1d620 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1d630 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1d640 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1d650 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1d660 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1d670 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1d680 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1d690 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1d6a0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1d6b0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1d6c0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1d6d0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1d6e0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1d6f0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1d700 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1d710 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1d720 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1d730 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1d740 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d750 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1d760 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1d770 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1d780 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1d790 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1d7a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1d7b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d7c0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1d7d0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1d7e0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1d7f0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1d800 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1d810 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1d820 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1d830 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1d840 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1d850 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1d860 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1d870 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d890 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1d8a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1d8b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1d8c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1d8d0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1d8e0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1d8f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1d900 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d910 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d920 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1d930 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d940 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d950 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d960 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1d970 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1d980 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1d990 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1d9a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d9b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1d9c0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1d9d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1d9e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d9f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1da00 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1da10 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1da20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1da30 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1da40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1da50 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1da60 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1da70 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1da80 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1da90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1daa0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1dab0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1dac0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1dad0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1daf0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1db00 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1db10 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1db20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1db30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1db40 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1db50 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1db60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1db70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1db80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1db90 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1dba0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1dbb0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1dbc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1dbd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dbe0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1dbf0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1dc00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1dc10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1dc20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1dc30 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1dc40 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1dc50 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1dc60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1dc70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1dc80 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1dc90 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1dca0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1dcb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1dcc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1dcd0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1dce0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1dcf0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1dd00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1dd10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1dd20 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1dd30 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1dd40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1dd50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1dd60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1dd70 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1dd80 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1dd90 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1dda0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ddb0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1ddc0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1ddd0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1dde0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ddf0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1de00 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1de10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1de20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1de30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1de40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1de50 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1de60 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1de70 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1de80 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1de90 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1dea0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1deb0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1dec0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ded0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1dee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1def0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1df00 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1df10 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1df20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1df30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1df40 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1df50 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1df60 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1df70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1df80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1df90 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1dfa0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1dfb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1dfc0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1dfd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dfe0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1dff0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1e000 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1e010 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e030 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1e040 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1e050 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1e060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e080 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1e090 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1e0a0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1e0b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e0c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e0d0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1e0e0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1e0f0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1e100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1e120 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1e130 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1e140 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e150 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e170 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1e180 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1e190 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1e1a0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1e1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e1c0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1e1d0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1e1e0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1e1f0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1e200 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1e210 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1e220 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1e230 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1e240 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1e250 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1e260 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1e270 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1e280 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1e290 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1e2a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1e2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e2c0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1e2d0 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
1e2e0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1e2f0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1e300 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1e310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1e320 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1e330 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1e340 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1e350 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1e360 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1e370 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1e380 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1e390 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1e3a0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1e3b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1e3c0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1e3d0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1e3e0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1e3f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1e400 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1e410 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1e420 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1e430 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1e440 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1e450 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1e460 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1e470 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1e480 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1e490 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1e4a0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1e4b0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1e4c0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1e4d0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1e4e0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1e4f0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1e500 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1e510 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1e520 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1e530 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1e540 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1e550 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1e560 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1e570 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1e580 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1e590 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1e5a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1e5b0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1e5c0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1e5d0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1e5e0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1e5f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1e600 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1e610 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1e620 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1e630 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1e640 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1e650 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1e660 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1e670 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1e680 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1e690 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1e6a0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1e6b0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1e6c0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1e6d0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1e6e0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1e6f0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1e700 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1e710 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1e720 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1e730 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1e740 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1e750 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1e760 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1e770 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1e780 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1e790 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1e7a0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1e7b0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1e7c0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1e7d0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1e7e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1e7f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1e800 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1e810 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1e820 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1e830 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1e840 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1e850 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1e860 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1e870 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1e880 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1e890 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1e8a0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1e8b0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1e8c0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1e8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1e8e0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1e8f0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1e900 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1e910 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1e920 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1e930 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1e940 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1e950 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1e960 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1e970 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1e980 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1e990 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1e9a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1e9b0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1e9c0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1e9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e9e0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1e9f0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1ea00 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1ea10 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1ea20 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1ea30 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1ea40 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1ea50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1ea60 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1ea70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ea80 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1ea90 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1eaa0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1eab0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1eac0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1ead0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1eae0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1eaf0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1eb00 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
1eb10 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
1eb20 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
1eb30 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1eb40 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1eb50 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1eb60 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1eb70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1eb80 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1eb90 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1eba0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1ebb0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1ebc0 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1ebd0 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1ebe0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1ebf0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1ec00 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1ec10 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1ec20 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1ec30 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1ec40 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1ec50 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1ec60 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1ec70 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1ec80 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1ec90 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1eca0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1ecb0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1ecc0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1ecd0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1ece0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1ecf0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1ed00 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1ed10 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1ed20 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1ed30 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1ed40 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1ed50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1ed60 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1ed70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1ed80 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1ed90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1eda0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1edb0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1edc0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1edd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ede0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1edf0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1ee00 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1ee10 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
1ee20 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1ee30 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1ee40 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1ee50 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1ee60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ee70 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1ee80 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1ee90 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
1eea0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1eeb0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
1eec0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
1eed0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1eee0 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
1eef0 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
1ef00 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1ef10 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1ef20 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1ef30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1ef40 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1ef50 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1ef60 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1ef70 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1ef80 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1ef90 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
1efa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1efb0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1efc0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1efd0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1efe0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1eff0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1f000 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1f010 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1f020 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1f030 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1f040 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1f050 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1f060 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1f070 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1f080 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1f090 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1f0a0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
1f0b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1f0c0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1f0d0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1f0e0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1f0f0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1f100 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1f110 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1f120 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
1f130 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
1f140 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1f150 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f160 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1f170 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1f180 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1f190 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1f1a0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1f1b0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
1f1c0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
1f1d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1f1e0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
1f1f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1f200 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1f210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1f220 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1f230 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1f240 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1f250 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1f260 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1f270 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1f280 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1f290 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1f2a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1f2b0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1f2c0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1f2d0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1f2e0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1f2f0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1f300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f310 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1f320 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1f330 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1f340 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1f350 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1f360 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1f370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1f380 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1f390 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1f3a0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1f3b0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1f3c0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1f3d0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1f3e0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1f3f0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1f400 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1f410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f420 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
1f430 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
1f440 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f450 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1f460 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1f470 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1f480 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1f490 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1f4a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1f4b0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1f4c0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1f4d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1f4e0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
1f4f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1f500 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
1f510 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
1f520 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
1f530 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1f540 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1f550 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1f560 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1f570 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1f580 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1f590 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1f5a0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1f5b0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1f5c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1f5d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1f5e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1f5f0 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
1f600 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1f610 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1f620 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1f630 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
1f640 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
1f650 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
1f660 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
1f670 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
1f680 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
1f690 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
1f6a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
1f6b0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
1f6c0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
1f6d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1f6e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1f6f0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1f700 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
1f710 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1f720 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1f730 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1f740 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1f750 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
1f760 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
1f770 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1f780 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1f790 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1f7a0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1f7b0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1f7c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1f7d0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1f7e0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1f7f0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1f800 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1f810 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1f820 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1f830 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1f840 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1f850 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
1f860 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
1f870 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
1f880 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
1f890 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
1f8a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1f8b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1f8c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1f8d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1f8e0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1f8f0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1f900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f910 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1f920 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1f930 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1f940 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1f950 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1f960 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1f970 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1f980 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1f990 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1f9a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1f9b0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1f9c0 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1f9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f9e0 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1f9f0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1fa00 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1fa10 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1fa20 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1fa30 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1fa40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1fa50 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1fa60 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1fa70 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1fa80 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1fa90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1faa0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1fab0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1fac0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1fad0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1fae0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1faf0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1fb00 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1fb10 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1fb20 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1fb30 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1fb40 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1fb50 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1fb60 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1fb70 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1fb80 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1fb90 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1fba0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1fbb0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1fbc0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
1fbd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1fbe0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1fbf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1fc00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
1fc10 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
1fc20 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
1fc30 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1fc40 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
1fc50 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1fc60 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
1fc70 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
1fc80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1fc90 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1fca0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
1fcb0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1fcc0 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
1fcd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1fce0 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1fcf0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1fd00 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1fd10 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1fd20 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1fd30 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1fd40 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
1fd50 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1fd60 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1fd70 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1fd80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1fd90 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1fda0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fdb0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1fdc0 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1fdd0 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1fde0 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1fdf0 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1fe00 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1fe10 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1fe20 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1fe30 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1fe40 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1fe50 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1fe60 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1fe70 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1fe80 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1fe90 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1fea0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1feb0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1fec0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1fed0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1fee0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1fef0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1ff00 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1ff10 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1ff20 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1ff30 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1ff40 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1ff50 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1ff60 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1ff70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ff80 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1ff90 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
1ffa0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1ffb0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
1ffc0 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
1ffd0 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
1ffe0 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
1fff0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
20000 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
20010 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
20020 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
20030 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
20040 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
20050 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
20060 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
20070 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
20080 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
20090 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
200a0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
200b0 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
200c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
200d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
200e0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
200f0 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
20100 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
20110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
20120 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
20130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
20140 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
20150 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
20160 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
20170 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
20180 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
20190 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
201a0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
201b0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
201c0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
201d0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
201e0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
201f0 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
20200 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
20210 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20220 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
20230 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
20240 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
20250 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
20260 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
20270 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
20280 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
20290 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
202a0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
202b0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
202c0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
202d0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
202e0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
202f0 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
20300 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
20310 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
20320 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
20330 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
20340 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
20350 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
20360 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
20370 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
20380 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
20390 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
203a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
203b0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
203c0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
203d0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
203e0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
203f0 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
20400 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
20410 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
20420 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
20430 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
20440 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
20450 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
20460 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
20470 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
20480 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
20490 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
204a0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
204b0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
204c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
204d0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
204e0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
204f0 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
20500 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77   path. .** ^On w
20510 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73  indows, the firs
20520 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  t component of a
20530 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20  n absolute path 
20540 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73  .** is a drive s
20550 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e  pecification (e.
20560 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20  g. "C:")..**.** 
20570 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
20580 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
20590 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
205a0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
205b0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
205c0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
205d0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
205e0 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
205f0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
20600 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
20610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
20620 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
20630 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77  prets the follow
20640 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20  ing three query 
20650 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
20660 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
20670 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
20680 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
20690 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
206a0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
206b0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
206c0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
206d0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
206e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
206f0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
20700 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
20710 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
20720 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
20730 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
20740 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
20750 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
20760 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
20770 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
20780 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
20790 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
207a0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
207b0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
207c0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
207d0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
207e0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
207f0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
20800 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
20810 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
20820 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
20830 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
20840 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
20850 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20860 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20870 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
20880 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
20890 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
208a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
208b0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
208c0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
208d0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
208e0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
208f0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
20900 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
20910 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
20920 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
20930 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
20940 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
20950 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
20960 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
20970 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
20980 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
20990 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
209a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
209b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
209c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
209d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
209e0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
209f0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
20a00 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
20a10 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
20a20 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20a30 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
20a40 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
20a50 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
20a60 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
20a70 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
20a80 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
20a90 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
20aa0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
20ab0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
20ac0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
20ad0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
20ae0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
20af0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
20b00 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
20b10 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
20b20 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
20b30 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
20b40 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
20b50 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
20b60 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
20b70 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
20b80 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
20b90 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
20ba0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
20bb0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
20bc0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
20bd0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
20be0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
20bf0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
20c00 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
20c10 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
20c20 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
20c30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20c40 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
20c50 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
20c60 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
20c70 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
20c80 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
20c90 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
20ca0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
20cb0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
20cc0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
20cd0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
20ce0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
20cf0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
20d00 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
20d10 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
20d20 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
20d30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20d40 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
20d50 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
20d60 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
20d70 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
20d80 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
20d90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20da0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
20db0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
20dc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
20dd0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
20de0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
20df0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
20e00 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
20e10 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
20e20 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
20e30 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
20e40 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
20e50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20e60 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
20e70 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20e80 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
20e90 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
20ea0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
20eb0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
20ec0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
20ed0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
20ee0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
20ef0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20f00 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
20f10 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
20f20 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
20f30 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
20f40 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
20f50 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
20f60 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
20f70 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
20f80 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
20f90 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
20fa0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
20fb0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
20fc0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
20fd0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
20fe0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
20ff0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
21000 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
21010 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
21020 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
21030 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
21040 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
21050 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
21060 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
21070 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
21080 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
21090 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
210a0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
210b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
210c0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
210d0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
210e0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
210f0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
21100 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
21110 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21120 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
21130 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
21140 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
21150 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21160 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
21170 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
21180 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
21190 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
211a0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
211b0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
211c0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
211d0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
211e0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
211f0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
21200 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
21210 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
21220 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
21230 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
21240 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
21250 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
21260 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
21270 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
21280 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
21290 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
212a0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
212b0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
212c0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
212d0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
212e0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
212f0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
21300 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
21310 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
21320 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
21330 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
21340 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
21350 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
21360 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
21370 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
21380 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
21390 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
213a0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
213b0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
213c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
213d0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
213e0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
213f0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
21400 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
21410 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
21420 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21430 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
21440 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
21450 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
21460 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
21470 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21480 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
21490 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
214a0 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
214b0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
214c0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
214d0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
214e0 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
214f0 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
21500 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
21510 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
21520 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
21530 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
21540 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
21550 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
21560 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
21570 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
21580 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
21590 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
215a0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
215b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
215c0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
215d0 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
215e0 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
215f0 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
21600 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
21610 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
21620 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
21630 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
21640 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
21650 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
21660 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
21670 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
21680 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
21690 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
216a0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
216b0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
216c0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
216d0 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
216e0 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
216f0 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
21700 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
21710 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
21720 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
21730 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
21740 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
21750 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
21760 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
21770 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
21780 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
21790 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
217a0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
217b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
217c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
217d0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
217e0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
217f0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
21800 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
21810 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
21820 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
21830 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
21840 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
21850 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
21860 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
21870 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
21880 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
21890 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
218a0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
218b0 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
218c0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
218d0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
218e0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
218f0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
21900 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
21910 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
21920 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
21930 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
21940 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
21950 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
21960 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
21970 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
21980 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
21990 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
219a0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
219b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
219c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
219d0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
219e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
219f0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
21a00 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
21a10 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
21a20 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
21a30 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
21a40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
21a50 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
21a60 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
21a70 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
21a80 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
21a90 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
21aa0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21ab0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21ac0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
21ad0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
21ae0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
21af0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
21b00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
21b10 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
21b20 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
21b30 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
21b40 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
21b50 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
21b60 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
21b70 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
21b80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
21b90 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
21ba0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
21bb0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
21bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
21bd0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
21be0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
21bf0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
21c00 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
21c10 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
21c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
21c30 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
21c40 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
21c50 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
21c60 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
21c70 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
21c80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
21c90 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
21ca0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
21cb0 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
21cc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
21cd0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
21ce0 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
21cf0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
21d00 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
21d10 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
21d20 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
21d30 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
21d40 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
21d50 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
21d60 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
21d70 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
21d80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
21d90 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
21da0 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
21db0 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
21dc0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
21dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
21de0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
21df0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
21e00 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
21e10 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
21e20 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
21e30 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
21e40 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
21e50 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
21e60 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
21e70 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
21e80 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
21e90 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
21ea0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
21eb0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
21ec0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
21ed0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
21ee0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
21ef0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
21f00 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21f10 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
21f20 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
21f30 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
21f40 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
21f50 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
21f60 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
21f70 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
21f80 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
21f90 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
21fa0 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
21fb0 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
21fc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
21fd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
21fe0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
21ff0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
22000 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
22010 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
22020 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
22030 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
22040 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
22050 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22060 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
22070 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
22080 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
22090 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
220a0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
220b0 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
220c0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
220d0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
220e0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
220f0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
22100 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
22110 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22120 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
22130 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
22140 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
22150 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
22160 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
22170 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22180 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
22190 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
221a0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
221b0 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
221c0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
221d0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
221e0 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
221f0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
22200 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
22210 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
22220 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
22230 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
22240 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
22250 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
22260 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
22270 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
22280 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
22290 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
222a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
222b0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
222c0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
222d0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
222e0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
222f0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
22300 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
22310 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
22320 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
22330 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
22340 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
22350 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
22360 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
22370 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
22380 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
22390 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
223a0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
223b0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
223c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
223d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
223e0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
223f0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
22400 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
22410 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
22420 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22430 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22440 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
22450 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
22460 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
22470 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
22480 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
22490 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
224a0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
224b0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
224c0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
224d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
224e0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
224f0 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
22500 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
22510 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
22520 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
22530 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
22540 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
22550 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
22560 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22570 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
22580 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
22590 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
225a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
225b0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
225c0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
225d0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
225e0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
225f0 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
22600 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
22610 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
22620 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
22630 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
22640 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
22650 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
22660 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
22670 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
22680 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
22690 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
226a0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
226b0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
226c0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
226d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
226e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
226f0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
22700 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
22710 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
22720 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
22730 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
22740 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
22750 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
22760 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
22770 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
22780 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
22790 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
227a0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
227b0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
227c0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
227d0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
227e0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
227f0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
22800 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
22810 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
22820 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
22830 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
22840 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
22850 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
22860 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
22870 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
22880 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
22890 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
228a0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
228b0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
228c0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
228d0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
228e0 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
228f0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
22900 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
22910 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
22920 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
22930 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
22940 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
22950 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
22960 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
22970 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
22980 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
22990 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
229a0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
229b0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
229c0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
229d0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
229e0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
229f0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
22a00 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
22a10 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
22a20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
22a30 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
22a40 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
22a50 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
22a60 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
22a70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
22a80 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
22a90 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
22aa0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
22ab0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
22ac0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
22ad0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
22ae0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
22af0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
22b00 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
22b10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
22b20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
22b30 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
22b40 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
22b50 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
22b60 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
22b70 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
22b80 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
22b90 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
22ba0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
22bb0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
22bc0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
22bd0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
22be0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
22bf0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
22c00 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
22c10 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
22c20 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
22c30 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
22c40 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
22c50 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
22c60 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
22c70 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
22c80 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c  t be set..*/.SQL
22c90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22ca0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
22cb0 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
22cc0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22cd0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
22ce0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
22cf0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
22d00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22d10 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
22d20 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
22d30 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22d40 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
22d50 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
22d60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22d70 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
22d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22d90 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
22da0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
22db0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
22dc0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
22dd0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
22de0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
22df0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
22e00 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
22e10 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
22e20 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
22e30 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
22e40 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
22e50 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
22e60 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
22e70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
22e80 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
22e90 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
22ea0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
22eb0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
22ec0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
22ed0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
22ee0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
22ef0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
22f00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22f10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
22f20 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
22f30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
22f40 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
22f50 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
22f60 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
22f70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
22f80 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
22f90 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
22fa0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
22fb0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
22fc0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
22fd0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
22fe0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
22ff0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23000 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
23010 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
23020 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
23030 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
23040 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
23050 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
23060 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23070 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
23080 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
23090 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
230a0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
230b0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
230c0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
230d0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
230e0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
230f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
23100 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
23110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
23120 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
23130 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
23140 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
23150 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
23160 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
23170 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
23180 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
23190 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
231a0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
231b0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
231c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
231d0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
231e0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
231f0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
23200 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
23210 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
23220 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
23230 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
23240 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
23250 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
23260 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
23270 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23280 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
23290 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
232a0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
232b0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
232c0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
232d0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
232e0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
232f0 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
23300 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
23310 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
23320 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
23330 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
23340 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
23350 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
23360 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
23370 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
23380 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
23390 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
233a0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
233b0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
233c0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
233d0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
233e0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
233f0 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
23400 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
23410 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
23420 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
23430 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
23440 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
23450 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
23460 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23470 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
23480 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
23490 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
234a0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
234b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
234c0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
234d0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
234e0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
234f0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
23500 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
23510 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
23520 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
23530 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
23540 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
23550 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
23560 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
23570 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
23580 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
23590 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
235a0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
235b0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
235c0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
235d0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
235e0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
235f0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
23600 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
23610 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
23620 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
23630 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
23640 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
23650 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
23660 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
23670 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
23680 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
23690 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
236a0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
236b0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
236c0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
236d0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
236e0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
236f0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
23700 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
23710 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
23720 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
23730 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
23740 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
23750 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
23760 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
23770 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
23780 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
23790 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
237a0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
237b0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
237c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
237d0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
237e0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
237f0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
23800 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
23810 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
23820 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
23830 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
23840 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
23850 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
23860 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
23870 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
23880 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
23890 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
238a0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
238b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
238c0 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
238d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
238e0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
238f0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
23900 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
23910 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
23920 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
23930 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
23940 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
23950 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
23960 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
23970 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
23980 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
23990 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
239a0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
239b0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
239c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
239d0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
239e0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
239f0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
23a00 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
23a10 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
23a20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
23a30 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
23a40 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
23a50 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
23a60 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
23a70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23a80 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
23a90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
23aa0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
23ab0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
23ac0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
23ad0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
23ae0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
23af0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23b00 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
23b10 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
23b20 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
23b30 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
23b40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
23b50 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
23b60 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
23b70 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
23b80 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
23b90 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
23ba0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
23bb0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
23bc0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23bd0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
23be0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
23bf0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
23c00 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
23c10 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
23c20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
23c30 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
23c40 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
23c50 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
23c60 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
23c70 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23c80 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23c90 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
23ca0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
23cb0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
23cc0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
23cd0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
23ce0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
23cf0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
23d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23d10 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
23d20 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
23d30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
23d40 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
23d50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
23d60 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
23d70 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
23d80 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
23d90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23da0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
23db0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
23dc0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
23dd0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
23de0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23df0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
23e00 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
23e10 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
23e20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
23e30 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
23e40 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
23e50 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
23e60 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
23e70 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
23e80 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
23e90 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
23ea0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
23eb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
23ed0 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
23ee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
23ef0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
23f00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23f10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
23f20 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
23f30 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
23f40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23f50 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
23f60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
23f70 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
23f80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23f90 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
23fa0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
23fb0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
23fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23fd0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
23fe0 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
23ff0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24000 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
24010 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
24020 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
24030 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
24040 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
24050 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
24060 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
24070 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24080 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
24090 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
240a0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
240b0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
240c0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
240d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
240e0 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
240f0 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
24100 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24110 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
24120 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
24130 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
24140 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
24150 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
24160 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24170 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24180 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24190 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
241a0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
241b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
241c0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
241d0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
241e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
241f0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
24200 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
24210 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
24220 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
24230 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
24240 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
24250 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
24260 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
24270 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24280 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
24290 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
242a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
242b0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
242c0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
242d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
242e0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
242f0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
24300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24310 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
24320 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
24330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24340 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24350 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
24360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24370 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24380 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
24390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
243a0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
243b0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
243c0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
243d0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
243e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
243f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
24400 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
24410 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
24420 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
24430 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
24440 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
24450 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
24460 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
24470 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
24480 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
24490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
244a0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
244b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
244c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
244d0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
244e0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
244f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
24500 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24510 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
24520 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
24530 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24540 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
24550 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
24560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
24570 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
24580 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
24590 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
245a0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
245b0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
245c0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
245d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
245e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
245f0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
24600 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
24610 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
24620 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
24630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24640 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
24650 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
24660 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
24670 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
24680 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
24690 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
246a0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
246b0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
246c0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
246d0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
246e0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
246f0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
24700 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
24710 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
24720 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
24730 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
24740 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
24750 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
24760 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
24770 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
24780 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
24790 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
247a0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
247b0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
247c0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
247d0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
247e0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
247f0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
24800 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
24810 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
24820 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
24830 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
24840 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
24850 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
24860 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
24870 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
24880 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
24890 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
248a0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
248b0 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
248c0 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
248d0 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
248e0 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
248f0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
24900 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
24910 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
24920 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
24930 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
24940 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
24950 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
24960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
24970 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
24980 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
24990 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
249a0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
249b0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
249c0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
249d0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
249e0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
249f0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
24a00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
24a10 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
24a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24a30 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
24a40 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
24a50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24a60 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
24a70 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
24a80 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
24a90 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
24aa0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
24ab0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
24ac0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
24ad0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
24ae0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
24af0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
24b00 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
24b10 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
24b20 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
24b30 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
24b40 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
24b50 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
24b60 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
24b70 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
24b80 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
24b90 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
24ba0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
24bb0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
24bc0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
24bd0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
24be0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
24bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
24c00 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
24c10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
24c20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
24c40 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
24c50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24c60 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
24c70 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
24c80 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
24c90 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
24ca0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
24cb0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
24cc0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
24cd0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
24ce0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
24cf0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
24d00 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
24d10 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
24d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
24d30 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
24d40 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
24d50 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
24d60 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
24d70 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
24d80 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
24d90 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
24da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
24db0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
24dc0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
24dd0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
24de0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
24df0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
24e00 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
24e10 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
24e20 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
24e30 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
24e40 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
24e50 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
24e60 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
24e70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
24e80 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
24e90 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
24ea0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
24eb0 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
24ec0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
24ed0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
24ee0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
24ef0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
24f00 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
24f10 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
24f20 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
24f30 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
24f40 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
24f50 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
24f60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24f70 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
24f80 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
24f90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
24fa0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
24fb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
24fc0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
24fd0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
24fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
24ff0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
25000 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
25010 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
25020 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
25030 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
25040 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
25050 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
25060 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
25070 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
25080 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
25090 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
250a0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
250b0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
250c0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
250d0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
250e0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
250f0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
25100 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
25110 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
25120 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
25130 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
25140 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
25150 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
25160 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
25170 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
25180 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
25190 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
251a0 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
251b0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
251c0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
251d0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
251e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
251f0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
25200 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
25210 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
25220 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
25230 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
25240 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
25250 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
25260 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
25270 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
25280 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
25290 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
252a0 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
252b0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
252c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
252d0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
252e0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
252f0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
25300 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
25310 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
25320 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
25330 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
25340 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ol>.*/.SQL
25350 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25360 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
25370 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
25380 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
25390 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
253a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
253b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
253c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
253d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
253e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
253f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25400 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25410 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25420 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25430 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
25440 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
25450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
25460 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
25470 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
25480 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
25490 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
254a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
254b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
254c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
254d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
254e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
254f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
25500 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25510 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
25520 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
25530 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
25540 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
25550 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
25560 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
25570 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
25580 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
25590 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
255a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
255b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
255c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
255d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
255e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
255f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
25600 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
25610 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
25620 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
25630 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
25640 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
25650 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25660 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
25670 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25680 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25690 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
256a0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
256b0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
256c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
256d0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
256e0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
256f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
25700 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
25710 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
25720 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
25730 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
25740 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
25750 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
25760 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25770 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
25780 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25790 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
257a0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
257b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
257c0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
257d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
257e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
257f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
25800 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
25810 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
25820 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
25830 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
25840 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25850 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
25860 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
25870 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
25880 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
25890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
258a0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
258b0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
258c0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
258d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
258e0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
258f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
25900 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
25910 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
25920 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25930 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
25940 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
25950 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
25960 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
25970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
25980 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25990 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
259a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
259b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
259c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
259d0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
259e0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
259f0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
25a00 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
25a10 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
25a20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
25a30 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
25a40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25a50 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
25a60 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
25a70 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
25a80 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
25a90 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
25aa0 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
25ab0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
25ac0 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
25ad0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
25ae0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25af0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
25b00 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
25b10 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
25b20 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
25b30 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
25b40 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
25b50 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
25b60 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
25b70 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
25b80 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
25b90 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
25ba0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
25bb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
25bc0 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
25bd0 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
25be0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25bf0 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
25c00 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
25c10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
25c20 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
25c30 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
25c40 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
25c50 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
25c60 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
25c70 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
25c80 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
25c90 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
25ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
25cb0 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
25cc0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25cd0 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
25ce0 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
25cf0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
25d00 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
25d10 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
25d20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
25d30 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
25d40 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
25d50 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
25d60 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
25d70 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
25d80 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
25d90 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
25da0 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
25db0 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
25dc0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
25dd0 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
25de0 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
25df0 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
25e00 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
25e10 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
25e20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
25e30 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
25e40 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
25e50 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
25e60 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25e70 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
25e80 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
25e90 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
25ea0 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
25eb0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
25ec0 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
25ed0 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
25ee0 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
25ef0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
25f00 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
25f10 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
25f20 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
25f30 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
25f40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
25f50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25f70 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
25f80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
25f90 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
25fa0 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
25fb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
25fc0 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
25fd0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
25fe0 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
25ff0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26000 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
26010 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
26020 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
26030 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26040 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
26050 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
26060 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
26070 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
26080 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
26090 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
260a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
260b0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
260c0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
260d0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
260e0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
260f0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
26100 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
26110 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
26120 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
26130 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
26140 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
26150 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
26160 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
26170 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
26180 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
26190 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
261a0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
261b0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
261c0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
261d0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
261e0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
261f0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
26200 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
26210 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
26220 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
26230 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
26240 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
26250 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
26260 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
26270 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
26280 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
26290 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
262a0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
262b0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
262c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
262d0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
262e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
262f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26300 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
26310 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
26320 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
26330 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26340 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
26350 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26360 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
26370 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
26380 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
26390 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
263a0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
263b0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
263c0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
263d0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
263e0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
263f0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
26400 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
26410 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
26420 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26430 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
26440 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
26450 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
26460 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
26470 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
26480 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26490 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
264a0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
264b0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
264c0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
264d0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
264e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
264f0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
26500 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
26510 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
26520 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
26530 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26540 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
26550 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
26560 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
26570 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
26580 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
26590 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
265a0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
265b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
265c0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
265d0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
265e0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
265f0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
26600 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
26610 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
26620 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
26630 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
26640 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
26650 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
26660 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
26670 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
26680 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
26690 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
266a0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
266b0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
266c0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
266d0 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
266e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
266f0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
26700 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
26710 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
26720 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
26730 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
26740 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
26750 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
26760 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
26770 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
26780 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
26790 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
267a0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
267b0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
267c0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
267d0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
267e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
267f0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
26800 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
26810 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
26820 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
26830 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
26840 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
26850 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
26860 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
26870 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
26880 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
26890 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
268a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
268b0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
268c0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
268d0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
268e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
268f0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
26900 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
26910 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
26920 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
26930 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
26940 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26950 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
26960 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
26970 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
26980 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
26990 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
269a0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
269b0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
269c0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
269d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
269e0 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
269f0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
26a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
26a10 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
26a20 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
26a30 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
26a40 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
26a50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
26a60 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
26a70 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
26a80 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
26a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26aa0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
26ab0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
26ac0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
26ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
26ae0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
26af0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
26b00 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
26b10 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
26b20 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
26b30 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
26b40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
26b50 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
26b60 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
26b70 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
26b80 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
26b90 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
26ba0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
26bb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
26bc0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
26bd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
26bf0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
26c00 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
26c10 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
26c20 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
26c30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
26c40 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
26c50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
26c60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
26c70 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
26c80 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
26c90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
26ca0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
26cb0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
26cc0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
26cd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
26ce0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
26cf0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
26d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
26d10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
26d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26d30 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
26d40 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
26d50 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
26d60 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
26d70 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
26d80 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
26d90 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
26da0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
26db0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
26dc0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
26dd0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
26de0 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
26df0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
26e00 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
26e10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
26e20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
26e30 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
26e40 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
26e50 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
26e60 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
26e70 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
26e80 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
26e90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
26ea0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
26eb0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
26ec0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
26ed0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
26ee0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
26ef0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
26f00 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
26f10 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
26f20 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
26f30 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
26f40 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
26f50 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
26f60 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
26f70 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
26f80 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
26f90 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
26fa0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
26fb0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
26fc0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
26fd0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
26fe0 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
26ff0 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
27000 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
27010 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27020 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
27030 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
27040 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
27050 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
27060 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
27070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
27080 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
27090 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
270a0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
270b0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
270c0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
270d0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
270e0 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
270f0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
27100 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
27110 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
27120 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
27130 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
27140 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
27150 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
27160 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
27170 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
27180 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
27190 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
271a0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
271b0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
271c0 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
271d0 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
271e0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
271f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27200 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
27210 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
27220 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
27230 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
27240 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
27250 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
27260 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
27270 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
27280 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
27290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
272a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
272b0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
272c0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
272d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
272e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
272f0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
27300 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
27310 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
27320 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
27330 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
27340 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
27350 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27360 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27370 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
27380 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
27390 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
273a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
273b0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
273c0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
273d0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
273e0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
273f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27400 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27410 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
27420 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27430 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
27440 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
27450 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
27460 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
27470 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
27480 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
27490 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
274a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
274b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
274c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
274d0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
274e0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
274f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27500 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
27510 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
27520 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
27530 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27540 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
27550 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
27560 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61  6() then that pa
27570 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
27580 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
27590 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
275a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
275b0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
275c0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
275d0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
275e0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
275f0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
27600 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
27610 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
27620 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27630 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27640 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
27650 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
27660 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
27670 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
27680 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
27690 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
276a0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
276b0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
276c0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
276d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
276e0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
276f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27700 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
27710 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
27720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27730 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
27740 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
27750 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
27760 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
27770 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
27780 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
27790 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
277a0 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
277b0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
277c0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
277d0 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
277e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
277f0 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69  _blob(),.** sqli
27800 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
27810 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
27820 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e  _text16() fails.
27830 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69    .** ^If the fi
27840 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
27850 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
27860 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
27870 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
27880 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
27890 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
278a0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
278b0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
278c0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
278d0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
278e0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
278f0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
27900 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
27910 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
27920 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
27930 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
27940 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
27950 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
27960 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
27970 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
27980 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
27990 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
279a0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
279b0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
279c0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
279d0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
279e0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
279f0 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
27a00 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
27a10 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
27a20 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
27a30 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
27a40 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
27a50 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
27a60 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
27a70 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
27a80 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
27a90 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
27aa0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
27ab0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
27ac0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
27ad0 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
27ae0 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
27af0 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
27b00 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
27b10 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
27b20 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
27b30 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
27b40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
27b50 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
27b60 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
27b70 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
27b80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
27b90 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
27ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
27bb0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
27bc0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
27bd0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
27be0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
27bf0 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
27c00 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
27c10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
27c20 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
27c30 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
27c40 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
27c50 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
27c60 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
27c70 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
27c80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27c90 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
27ca0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
27cb0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
27cc0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27cd0 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
27ce0 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
27cf0 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
27d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
27d10 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
27d20 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
27d30 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
27d40 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
27d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27d60 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
27d70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
27d80 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
27d90 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
27da0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
27db0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
27dc0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
27dd0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
27de0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27df0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
27e00 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
27e10 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
27e20 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
27e30 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
27e40 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
27e50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
27e60 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
27e70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27e80 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
27e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27ea0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
27eb0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
27ec0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
27ed0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
27ee0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
27ef0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
27f00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
27f10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27f20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
27f30 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
27f40 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
27f50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
27f70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27f80 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  nt, int);.SQLITE
27f90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27fa0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
27fb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27fc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
27fd0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27fe0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
27ff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28000 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
28010 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
28020 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
28030 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28040 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
28050 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28060 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28080 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28090 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
280a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
280b0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
280c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
280d0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
280e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
280f0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
28100 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
28110 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28120 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
28130 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28140 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
28150 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
28160 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
28170 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
28180 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
28190 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
281a0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
281b0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
281c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
281d0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
281e0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
281f0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
28200 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
28210 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
28220 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
28230 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
28240 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
28250 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
28260 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
28270 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
28280 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
28290 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
282a0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
282b0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
282c0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
282d0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
282e0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
282f0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
28300 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
28310 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
28320 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
28330 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
28340 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
28350 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
28360 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
28370 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
28380 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
28390 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
283a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
283b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
283c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
283d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
283e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
283f0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
28400 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
28410 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
28420 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28440 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
28450 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28460 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
28470 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
28480 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
28490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
284a0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
284b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
284c0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
284d0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
284e0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
284f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28500 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
28510 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
28520 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
28530 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
28540 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
28550 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
28560 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
28570 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
28580 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
28590 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
285a0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
285b0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
285c0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
285d0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
285e0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
285f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
28600 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
28610 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
28620 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
28630 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
28640 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
28650 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
28660 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
28670 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
28680 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
28690 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
286a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
286b0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
286c0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
286d0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
286e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
286f0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
28700 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
28710 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
28720 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
28730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28740 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
28750 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
28760 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
28770 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
28780 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
28790 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
287a0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
287b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
287c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
287d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
287e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
287f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
28800 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
28810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28820 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
28830 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
28840 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28850 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
28860 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28870 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28880 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28890 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
288a0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
288b0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
288c0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
288d0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
288e0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
288f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
28900 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
28910 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
28920 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
28930 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
28940 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
28950 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
28960 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
28970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28980 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
28990 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
289a0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
289b0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
289c0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
289d0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
289e0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
289f0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
28a00 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
28a10 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
28a20 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
28a30 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
28a40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
28a50 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
28a60 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
28a70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
28a80 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
28a90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28aa0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
28ab0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
28ac0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28ad0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28ae0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28af0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28b00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
28b10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
28b20 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
28b30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28b40 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
28b50 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
28b60 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
28b70 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
28b80 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
28b90 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
28ba0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
28bb0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
28bc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28bd0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
28be0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28bf0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
28c00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
28c10 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
28c20 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
28c30 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
28c40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
28c50 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
28c60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
28c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
28c80 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
28c90 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
28ca0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
28cb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28cc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
28cd0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
28ce0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28cf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
28d00 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
28d10 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
28d20 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
28d30 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
28d40 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
28d50 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
28d60 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
28d70 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28d80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
28d90 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
28da0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
28db0 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
28dc0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28dd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28de0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
28df0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28e00 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
28e10 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
28e20 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
28e30 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
28e40 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
28e50 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
28e60 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
28e70 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
28e80 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
28e90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28ea0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
28eb0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28ec0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
28ed0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28ee0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
28ef0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28f00 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28f10 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
28f20 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
28f30 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
28f40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28f50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
28f60 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
28f70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
28f80 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
28f90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
28fa0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
28fb0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
28fc0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
28fd0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
28fe0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28ff0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
29000 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
29010 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29020 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
29030 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
29040 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
29050 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
29060 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
29070 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
29080 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
29090 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
290a0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
290b0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
290c0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
290d0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
290e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
290f0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
29100 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29110 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
29120 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
29130 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
29140 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
29150 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
29160 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
29170 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
29180 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
29190 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
291a0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
291b0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
291c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
291d0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
291e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
291f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29200 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
29210 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
29220 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
29230 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
29240 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
29250 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
29260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
29270 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
29280 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
29290 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
292a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
292b0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
292c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
292d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
292e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
292f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29300 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
29310 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29320 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
29330 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29340 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
29350 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
29360 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
29370 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
29380 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
29390 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
293a0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
293b0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
293c0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
293d0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
293e0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
293f0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
29400 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
29410 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
29420 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
29430 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
29440 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
29450 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
29460 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
29470 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
29480 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
29490 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
294a0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
294b0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
294c0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
294d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
294e0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
294f0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
29500 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29510 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
29520 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
29530 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
29540 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
29550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
29560 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
29570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
29580 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
29590 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
295a0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
295b0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
295c0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
295d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
295e0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
295f0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
29600 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
29610 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
29620 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
29630 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
29640 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
29650 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
29660 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
29670 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
29680 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
29690 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
296a0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
296b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
296c0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
296d0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
296e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
296f0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
29700 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
29710 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
29720 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
29730 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
29740 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
29750 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
29760 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
29770 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
29780 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
29790 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
297a0 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
297b0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
297c0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
297d0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
297e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
297f0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
29800 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
29810 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
29820 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
29830 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
29840 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
29850 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
29860 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
29870 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
29880 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
29890 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
298a0 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
298b0 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
298c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
298d0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
298e0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
298f0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
29900 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
29910 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
29920 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
29930 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
29940 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
29950 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
29960 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
29970 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
29980 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
29990 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
299a0 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
299b0 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
299c0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
299d0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
299e0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
299f0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
29a00 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
29a10 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
29a20 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
29a30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
29a40 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
29a50 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
29a60 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29a70 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
29a80 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
29a90 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
29aa0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
29ab0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
29ac0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
29ad0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
29ae0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
29af0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
29b00 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
29b10 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
29b20 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
29b30 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
29b40 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
29b50 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
29b60 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
29b70 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
29b80 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
29b90 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
29ba0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
29bb0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
29bc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29bd0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
29be0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29bf0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
29c00 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
29c10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29c20 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
29c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
29c40 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
29c50 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29c60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
29c70 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29c80 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
29c90 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
29ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29cb0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
29cc0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29cd0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29ce0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
29cf0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
29d00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29d10 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
29d20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
29d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29d40 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
29d50 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
29d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29d70 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
29d80 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
29d90 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
29da0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
29db0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
29dc0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
29dd0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
29de0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
29df0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
29e00 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
29e10 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
29e20 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
29e30 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
29e40 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
29e50 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
29e60 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
29e70 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
29e80 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
29e90 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
29ea0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
29eb0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
29ec0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29ed0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
29ee0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
29ef0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
29f00 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
29f10 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
29f20 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
29f30 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
29f40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
29f50 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
29f60 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
29f70 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
29f80 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
29f90 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
29fa0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
29fb0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29fc0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
29fd0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
29fe0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
29ff0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2a000 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2a010 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2a020 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2a030 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2a040 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2a050 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2a060 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2a070 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2a080 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2a090 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2a0a0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2a0b0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2a0c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2a0d0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2a0e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2a0f0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2a100 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2a110 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2a120 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2a130 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2a140 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2a150 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2a160 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2a170 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2a180 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2a190 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2a1a0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2a1b0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2a1c0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2a1d0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2a1e0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
2a1f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2a200 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2a210 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2a220 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a230 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a240 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a250 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2a260 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a270 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2a280 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2a290 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2a2a0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2a2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a2c0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2a2d0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2a2e0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2a2f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a300 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a310 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2a320 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2a330 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2a340 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2a350 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2a360 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2a370 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2a380 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2a390 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2a3a0 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2a3b0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2a3c0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2a3d0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2a3e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2a3f0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2a400 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2a410 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2a420 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2a430 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2a440 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2a450 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a460 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2a470 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2a480 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2a490 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2a4a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a4b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a4c0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2a4d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2a4e0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2a4f0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2a500 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2a510 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2a520 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a530 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2a540 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2a550 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2a560 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2a570 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2a580 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2a590 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2a5a0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2a5b0 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2a5c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2a5d0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2a5e0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2a5f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a600 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2a610 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2a620 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2a630 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2a640 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2a650 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2a660 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2a670 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2a680 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2a690 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2a6a0 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2a6b0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2a6c0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2a6d0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2a6e0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2a6f0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2a700 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2a710 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2a720 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2a730 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2a740 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2a750 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2a760 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2a770 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2a780 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2a790 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2a7a0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2a7b0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2a7c0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2a7d0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2a7e0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2a7f0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2a800 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2a810 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2a820 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2a830 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2a840 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2a850 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2a860 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2a870 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2a880 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2a890 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a8a0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2a8b0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2a8c0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2a8d0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2a8e0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2a8f0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2a900 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2a910 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2a920 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2a930 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2a940 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2a950 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2a960 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2a970 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2a980 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2a990 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2a9a0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2a9b0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2a9c0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2a9d0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2a9e0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2a9f0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2aa00 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2aa10 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2aa20 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2aa30 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2aa40 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2aa50 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2aa60 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2aa70 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2aa80 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2aa90 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2aaa0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2aab0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2aac0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2aad0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2aae0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2aaf0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2ab00 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2ab10 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2ab20 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2ab30 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2ab40 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2ab50 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2ab60 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2ab70 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2ab80 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2ab90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2aba0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2abb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2abc0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2abd0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2abe0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2abf0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2ac00 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2ac10 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2ac20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2ac30 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2ac40 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2ac50 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2ac60 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2ac70 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2ac80 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2ac90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2aca0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2acb0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2acc0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2acd0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2ace0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2acf0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2ad00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2ad10 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2ad20 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2ad30 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2ad40 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2ad50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ad60 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2ad70 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2ad80 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2ad90 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2ada0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2adb0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2adc0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2add0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2ade0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2adf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ae00 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2ae10 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2ae20 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2ae30 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2ae40 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2ae50 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2ae60 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2ae70 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2ae80 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2ae90 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2aea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aeb0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2aec0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2aed0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2aee0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2aef0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2af00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2af10 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2af20 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2af30 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2af40 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2af50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2af60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2af70 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2af80 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2af90 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2afa0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2afb0 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2afc0 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2afd0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2afe0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2aff0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2b000 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2b010 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2b020 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2b030 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2b040 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2b050 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2b060 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2b070 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2b080 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2b090 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2b0a0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2b0b0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2b0c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2b0d0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2b0e0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2b0f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2b100 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2b110 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2b120 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2b130 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2b140 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2b150 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2b160 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2b170 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2b180 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b190 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2b1a0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2b1b0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2b1c0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2b1d0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2b1e0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2b1f0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2b200 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2b210 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2b220 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2b230 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2b240 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2b250 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2b260 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2b270 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2b280 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2b290 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2b2a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b2b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2b2c0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2b2d0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2b2e0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2b2f0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2b300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b310 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2b320 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2b330 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2b340 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2b350 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2b360 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2b370 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2b380 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b390 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2b3a0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2b3b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
2b3c0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2b3d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b3e0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2b3f0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2b400 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2b410 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2b420 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2b430 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2b440 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2b450 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2b460 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2b470 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2b480 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2b490 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2b4a0 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2b4b0 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2b4c0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2b4d0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2b4e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2b4f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2b500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2b510 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2b520 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2b530 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b540 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2b550 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2b560 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2b570 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2b580 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2b590 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2b5a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2b5b0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2b5c0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2b5d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2b5e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2b5f0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2b600 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2b610 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2b620 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2b630 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2b640 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2b650 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b660 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2b670 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2b680 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2b690 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2b6a0 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2b6b0 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2b6c0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2b6d0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2b6e0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2b6f0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2b700 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2b710 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2b720 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2b740 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
2b750 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b760 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2b770 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2b780 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b790 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2b7a0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2b7b0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2b7c0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2b7d0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2b7e0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2b7f0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2b800 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2b810 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2b820 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2b830 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2b840 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2b850 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2b860 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2b870 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2b880 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2b890 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2b8a0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2b8b0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2b8c0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2b8d0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2b8e0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2b8f0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2b900 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2b910 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2b920 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2b930 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2b940 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2b950 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2b960 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2b970 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2b980 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2b990 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2b9a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2b9b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2b9c0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2b9d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2b9e0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2b9f0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2ba00 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2ba10 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2ba20 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2ba30 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2ba40 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2ba50 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2ba60 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2ba70 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2ba80 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2ba90 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2baa0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2bab0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2bac0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2bad0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2bae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2baf0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2bb00 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2bb10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2bb20 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2bb30 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2bb40 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2bb50 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2bb60 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2bb70 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2bb80 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2bb90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2bba0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2bbb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bbc0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2bbd0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2bbe0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2bbf0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2bc00 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2bc10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bc20 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2bc30 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2bc40 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2bc50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2bc60 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2bc70 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2bc80 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2bc90 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2bca0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2bcb0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2bcc0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2bcd0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2bce0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2bcf0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2bd00 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2bd10 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2bd20 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2bd30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2bd40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2bd50 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2bd60 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2bd70 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2bd80 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2bd90 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2bda0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2bdb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2bdc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2bdd0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2bde0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2bdf0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2be00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2be10 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2be20 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2be30 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2be40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2be50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2be60 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2be70 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2be80 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2be90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2bea0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2beb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2bec0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2bed0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2bee0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2bef0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2bf00 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2bf10 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2bf20 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2bf30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2bf40 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2bf50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2bf60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bf70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2bf80 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2bf90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2bfa0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2bfb0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2bfc0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2bfd0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2bfe0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2bff0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2c000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c010 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2c020 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2c030 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2c040 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2c050 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2c060 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2c070 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2c080 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2c090 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2c0a0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2c0b0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2c0c0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2c0d0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2c0e0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2c0f0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2c100 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2c110 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2c120 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2c130 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2c140 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2c150 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2c160 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2c170 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2c180 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2c190 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2c1a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2c1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2c1c0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2c1d0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2c1e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2c1f0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2c200 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2c210 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2c220 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2c230 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2c240 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c250 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2c260 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2c270 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2c280 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c290 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2c2a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2c2b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2c2c0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2c2d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c2e0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2c2f0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2c300 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c310 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2c320 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2c330 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2c340 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c350 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2c360 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2c370 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2c380 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2c390 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2c3a0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2c3b0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2c3c0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2c3d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2c3e0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2c3f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c400 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2c410 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c420 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2c430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c440 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2c450 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2c460 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c470 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2c480 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2c490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c4a0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2c4b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2c4c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c4d0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2c4e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2c4f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2c500 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2c510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c520 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2c530 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2c540 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2c550 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2c560 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2c570 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c580 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2c590 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2c5a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c5b0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2c5c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2c5d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2c5e0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2c5f0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2c600 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2c610 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c620 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2c630 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c640 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2c650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c660 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2c670 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2c680 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2c690 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2c6a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2c6b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c6c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2c6d0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2c6e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c6f0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2c700 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2c710 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2c720 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2c730 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2c740 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2c750 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2c760 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2c770 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2c780 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2c790 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2c7a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2c7b0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2c7c0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2c7d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c7e0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2c7f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c800 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2c810 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2c820 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2c830 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2c840 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2c850 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2c860 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2c870 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2c880 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c890 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2c8a0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2c8b0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2c8c0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2c8d0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2c8e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c8f0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2c900 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c910 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2c920 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2c930 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2c940 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2c950 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2c960 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2c970 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2c980 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c990 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2c9a0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2c9b0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2c9c0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2c9d0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2c9e0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2c9f0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2ca00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2ca10 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2ca20 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2ca30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2ca40 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2ca50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2ca60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2ca70 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2ca80 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2ca90 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2caa0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2cab0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2cac0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2cad0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2cae0 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2caf0 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2cb00 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2cb10 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2cb20 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2cb30 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2cb40 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2cb50 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2cb60 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2cb70 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2cb80 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2cb90 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2cba0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2cbb0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2cbc0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2cbd0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2cbe0 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2cbf0 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2cc00 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2cc10 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2cc20 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2cc30 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2cc40 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2cc50 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2cc60 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2cc70 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2cc80 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2cc90 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2cca0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2ccb0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2ccc0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2ccd0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2cce0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2ccf0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2cd00 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2cd10 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2cd20 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2cd30 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2cd40 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2cd50 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2cd60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2cd70 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2cd80 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2cd90 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2cda0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2cdb0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2cdc0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2cdd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2cde0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2cdf0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2ce00 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2ce10 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2ce20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2ce30 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2ce40 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2ce50 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2ce60 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2ce70 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2ce80 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2ce90 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2cea0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2ceb0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2cec0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2ced0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2cee0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2cef0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2cf00 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2cf10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2cf20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2cf30 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2cf40 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2cf50 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2cf60 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2cf70 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2cf80 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2cf90 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2cfa0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2cfb0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2cfc0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2cfd0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2cfe0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2cff0 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2d000 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2d010 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2d020 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2d030 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2d040 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2d050 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2d060 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2d070 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2d080 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2d090 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2d0a0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2d0b0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2d0c0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2d0d0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2d0e0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2d0f0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2d100 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2d110 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2d120 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2d130 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2d140 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2d150 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2d160 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2d170 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2d180 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2d190 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2d1a0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2d1b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2d1c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2d1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d1e0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2d1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d200 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2d210 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2d220 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2d230 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2d240 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2d250 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2d260 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2d270 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2d280 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2d290 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2d2a0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2d2b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2d2c0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2d2d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2d2e0 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2d2f0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2d300 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2d310 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2d320 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2d330 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2d340 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2d350 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2d360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d370 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2d380 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2d390 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2d3a0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2d3b0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2d3c0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2d3d0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2d3e0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2d3f0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2d400 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2d410 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d420 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2d430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d440 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2d450 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2d460 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2d470 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2d480 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2d490 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2d4a0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2d4b0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2d4c0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2d4d0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2d4e0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2d4f0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2d500 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2d510 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2d520 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2d530 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2d540 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2d550 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2d560 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2d570 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2d580 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2d590 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2d5a0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2d5b0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2d5c0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2d5d0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2d5e0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2d5f0 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2d600 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2d610 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2d620 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2d630 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2d640 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2d650 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2d660 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2d670 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2d680 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d690 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2d6a0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2d6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d6c0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2d6d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d6e0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2d6f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d700 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2d710 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2d720 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2d730 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2d740 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d750 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2d760 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2d770 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2d780 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2d790 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2d7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d7b0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2d7c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2d7d0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2d7e0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2d7f0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2d800 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2d810 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2d820 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2d830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d840 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2d850 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2d860 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2d870 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2d880 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2d890 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2d8a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d8b0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2d8c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2d8d0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2d8e0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2d8f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2d900 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2d910 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2d920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d930 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2d940 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2d950 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2d960 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2d970 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2d980 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2d990 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2d9a0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2d9b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d9c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2d9d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2d9e0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2d9f0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2da00 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2da10 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2da20 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2da30 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2da40 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2da50 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2da60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2da70 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2da80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2da90 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
2daa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2dab0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
2dac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2dad0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2dae0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
2daf0 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
2db00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
2db10 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
2db20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
2db30 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
2db40 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
2db50 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
2db60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2db70 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
2db80 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
2db90 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
2dba0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2dbb0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
2dbc0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
2dbd0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53  E_NOMEM].)^.*/.S
2dbe0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2dbf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2dc00 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2dc10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dc20 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2dc30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2dc40 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2dc50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2dc60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2dc70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dc80 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2dc90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2dca0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
2dcb0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2dcc0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2dcd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dce0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
2dcf0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2dd00 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2dd10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2dd20 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2dd30 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2dd40 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2dd50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dd60 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2dd70 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
2dd80 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2dd90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2dda0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ddb0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2ddc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2ddd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dde0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ddf0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2de00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2de10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2de20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2de30 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2de40 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c  _API sqlite3_val
2de50 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2de60 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2de70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2de80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2de90 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2dea0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2deb0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2dec0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2ded0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2dee0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2def0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2df00 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2df10 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2df20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2df30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2df40 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2df50 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2df60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2df70 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2df80 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2df90 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2dfa0 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2dfb0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2dfc0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2dfd0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2dfe0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2dff0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e000 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2e010 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2e020 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2e030 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2e040 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2e050 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2e060 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2e070 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2e080 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2e090 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2e0a0 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2e0b0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2e0c0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2e0d0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2e0e0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2e0f0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2e100 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2e110 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2e120 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2e130 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e140 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2e150 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2e160 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2e170 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2e180 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2e190 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2e1a0 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2e1b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2e1c0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2e1d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2e1e0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2e1f0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2e200 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e210 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2e220 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2e230 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2e240 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2e250 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e260 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2e270 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2e280 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2e290 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2e2a0 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2e2b0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2e2c0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2e2d0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2e2e0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2e2f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2e300 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2e310 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2e320 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2e330 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2e340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2e350 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e360 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2e370 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2e380 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2e390 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2e3a0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2e3b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2e3c0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2e3d0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2e3e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e3f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2e400 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2e410 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2e420 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2e430 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2e440 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2e450 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2e460 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2e470 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2e480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e490 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2e4a0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2e4b0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2e4c0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2e4d0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2e4e0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2e4f0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2e500 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2e510 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2e520 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2e530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e540 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2e550 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2e560 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2e570 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2e580 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2e590 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2e5a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2e5b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e5c0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2e5d0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2e5e0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2e5f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2e600 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2e610 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2e620 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2e630 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e640 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2e650 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2e660 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2e670 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2e680 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2e690 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e6a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2e6b0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2e6c0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2e6d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2e6e0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2e6f0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2e700 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2e710 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e720 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2e730 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2e740 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2e750 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2e760 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2e770 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2e780 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
2e790 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2e7a0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2e7b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e7c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e7d0 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2e7e0 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2e7f0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2e800 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2e810 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2e820 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2e850 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2e860 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e870 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2e880 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2e890 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2e8a0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2e8b0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2e8c0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2e8d0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2e8e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2e8f0 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2e900 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2e910 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2e920 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2e930 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2e940 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2e950 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2e960 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2e970 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2e980 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2e990 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2e9a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2e9b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2e9c0 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2e9d0 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2e9e0 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2e9f0 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2ea00 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2ea10 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2ea20 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2ea30 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2ea40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2ea50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ea60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2ea70 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2ea80 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2ea90 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2eaa0 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2eab0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2eac0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2ead0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2eae0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2eaf0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2eb00 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2eb10 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2eb20 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2eb30 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2eb40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2eb50 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2eb60 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2eb70 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2eb80 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2eb90 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2eba0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2ebb0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2ebc0 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2ebd0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2ebe0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2ebf0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2ec00 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2ec10 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2ec20 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2ec30 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2ec40 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2ec50 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2ec60 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2ec70 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2ec80 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2ec90 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2eca0 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2ecb0 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2ecc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2ecd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2ece0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2ecf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2ed00 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2ed10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2ed20 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2ed30 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2ed40 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2ed50 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2ed60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2ed70 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2ed80 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2ed90 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2eda0 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2edb0 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2edc0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2edd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2ede0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2edf0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2ee00 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2ee10 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2ee20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2ee30 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2ee40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2ee50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2ee60 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2ee70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2ee80 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2ee90 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2eea0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2eeb0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2eec0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2eed0 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2eee0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2eef0 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2ef00 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2ef10 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2ef20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2ef30 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2ef40 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2ef50 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2ef60 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2ef70 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2ef80 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2ef90 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2efa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2efb0 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2efc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2efd0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2efe0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2eff0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2f000 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2f010 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2f020 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2f030 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2f040 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2f050 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2f060 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2f070 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2f080 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2f090 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2f0a0 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2f0b0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2f0c0 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2f0d0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2f0e0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2f0f0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2f100 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2f110 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2f120 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2f130 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2f140 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2f150 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2f160 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2f170 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2f180 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2f190 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2f1a0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2f1b0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2f1c0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2f1d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f1e0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2f1f0 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2f200 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2f210 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2f220 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2f230 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2f240 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2f250 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2f260 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2f270 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2f280 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2f290 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2f2a0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2f2b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2f2c0 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2f2d0 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2f2e0 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2f2f0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2f300 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2f310 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2f320 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2f330 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2f340 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2f350 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2f360 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2f370 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2f380 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2f390 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2f3a0 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2f3b0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2f3c0 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2f3d0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2f3e0 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2f3f0 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2f400 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2f410 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2f420 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2f430 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2f440 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2f450 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2f460 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2f470 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2f480 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2f490 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f4a0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2f4b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2f4c0 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2f4d0 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2f4e0 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2f4f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f500 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2f510 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2f520 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2f530 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2f540 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2f550 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2f560 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2f570 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2f580 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2f590 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2f5a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2f5b0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2f5c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2f5d0 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2f5e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2f5f0 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2f600 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2f610 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2f620 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2f630 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2f640 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2f650 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2f660 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2f670 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f680 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2f690 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2f6a0 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2f6b0 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2f6c0 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2f6d0 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2f6e0 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2f6f0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2f700 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2f710 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2f720 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2f730 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2f740 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2f750 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2f760 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2f770 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2f780 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f790 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2f7a0 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2f7b0 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2f7c0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2f7d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2f7e0 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2f7f0 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2f800 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2f810 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2f820 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2f830 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2f840 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2f850 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2f860 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2f870 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2f880 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2f890 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2f8a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2f8b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2f8c0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2f8d0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2f8e0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2f8f0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2f900 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f910 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2f920 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2f930 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2f940 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2f950 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2f960 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2f970 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2f980 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f990 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2f9a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f9b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2f9c0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2f9d0 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2f9e0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2f9f0 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2fa00 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2fa10 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2fa20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2fa30 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2fa40 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2fa50 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2fa60 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2fa70 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2fa80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2fa90 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2faa0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2fab0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2fac0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2fad0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2fae0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2faf0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2fb00 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2fb10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fb20 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fb30 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fb40 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2fb50 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fb60 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fb70 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2fb80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fb90 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2fba0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fbb0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2fbc0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2fbd0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2fbe0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2fbf0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2fc00 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2fc10 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2fc20 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2fc30 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fc40 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fc50 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2fc60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fc70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fc80 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2fc90 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2fca0 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
2fcb0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2fcc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2fcd0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2fce0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2fcf0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fd00 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2fd10 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fd20 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fd30 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fd40 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fd50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fd60 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fd70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fd80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fd90 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fda0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fdb0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2fdc0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2fdd0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2fde0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2fdf0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2fe00 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2fe10 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2fe20 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2fe30 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2fe40 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2fe50 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2fe60 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2fe70 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2fe80 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2fe90 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2fea0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2feb0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2fec0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2fed0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2fee0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2fef0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2ff00 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2ff10 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2ff20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2ff30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ff40 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2ff50 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2ff60 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2ff70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ff80 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2ff90 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2ffa0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2ffb0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2ffc0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2ffd0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2ffe0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2fff0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
30000 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
30010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
30020 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
30030 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
30040 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
30050 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
30060 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
30070 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
30080 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
30090 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
300a0 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
300b0 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
300c0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
300d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
300e0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
300f0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
30100 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
30110 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
30120 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
30130 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
30140 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30150 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30160 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
30170 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
30180 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
30190 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
301a0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
301b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
301c0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
301d0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
301e0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
301f0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
30200 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
30210 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  mt*);.SQLITE_API
30220 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
30230 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
30240 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
30250 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
30260 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30270 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
30280 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
30290 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
302a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
302b0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
302c0 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
302d0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
302e0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
302f0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
30300 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
30310 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
30320 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
30330 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
30340 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
30350 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
30360 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
30370 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
30380 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
30390 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
303a0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
303b0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
303c0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
303d0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
303e0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
303f0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
30400 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
30410 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
30420 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
30430 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
30440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30450 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
30460 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30470 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
30480 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
30490 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
304a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
304b0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
304c0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
304d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
304e0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
304f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
30500 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
30510 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30520 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
30530 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
30540 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30550 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
30560 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
30570 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
30580 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
30590 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
305a0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
305b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
305c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
305d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
305e0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
305f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30600 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
30610 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
30620 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
30630 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
30640 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30650 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
30660 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
30670 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
30680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
30690 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
306a0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
306b0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
306c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
306d0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
306e0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
306f0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
30700 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30710 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30720 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
30730 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
30740 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
30750 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
30760 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
30770 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30780 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30790 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
307a0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
307b0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
307c0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
307d0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
307e0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
307f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30800 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
30810 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30820 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
30830 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
30840 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
30850 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
30860 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
30870 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
30880 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
30890 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
308a0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
308b0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
308c0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
308d0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
308e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
308f0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
30900 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
30910 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
30920 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
30930 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
30940 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
30950 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
30960 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
30970 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
30980 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
30990 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
309a0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
309b0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
309c0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
309d0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
309e0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
309f0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
30a00 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
30a10 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
30a20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
30a30 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
30a40 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
30a50 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
30a60 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
30a70 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
30a80 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
30a90 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
30aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30ab0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
30ac0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
30ad0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
30ae0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
30af0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
30b00 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
30b10 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
30b20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30b30 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
30b40 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
30b50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30b60 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
30b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30b80 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
30b90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
30ba0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
30bb0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
30bc0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
30bd0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
30be0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
30bf0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
30c00 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54  meters..*/.SQLIT
30c10 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
30c20 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
30c30 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
30c40 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30c50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
30c60 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
30c70 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30c80 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30c90 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
30ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30cb0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
30cc0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
30cd0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
30ce0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30cf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
30d00 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
30d10 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30d20 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
30d30 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
30d40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
30d50 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30d60 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
30d70 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
30d80 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
30d90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
30da0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
30db0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
30dc0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30dd0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
30de0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
30df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30e00 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
30e10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30e20 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
30e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30e40 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
30e50 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
30e60 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
30e70 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
30e80 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
30e90 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30ea0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
30eb0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30ec0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
30ed0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
30ee0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
30ef0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
30f00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
30f10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
30f20 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
30f30 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
30f40 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
30f50 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
30f60 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
30f70 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
30f80 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30f90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
30fa0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
30fb0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
30fc0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
30fd0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
30fe0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
30ff0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
31000 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
31010 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
31020 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
31030 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
31040 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
31050 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
31060 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
31070 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31080 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
31090 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
310a0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
310b0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
310c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
310d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
310e0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
310f0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
31100 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
31110 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
31120 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
31130 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
31140 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
31150 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
31160 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
31170 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
31180 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
31190 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
311a0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
311b0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
311c0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
311d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
311e0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
311f0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
31200 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
31210 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
31220 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
31230 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31240 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
31250 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
31260 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
31270 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
31280 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31290 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
312a0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
312b0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
312c0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
312d0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
312e0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
312f0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
31300 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
31310 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
31320 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
31330 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
31340 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31350 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
31360 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
31370 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
31380 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
31390 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
313a0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
313b0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
313c0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
313d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
313e0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
313f0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
31400 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
31410 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
31420 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
31430 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
31440 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
31450 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
31460 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
31470 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
31480 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31490 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
314a0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
314b0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
314c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
314d0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
314e0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
314f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
31500 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
31510 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
31520 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
31530 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
31540 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
31550 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
31560 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
31570 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
31580 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
31590 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
315a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
315b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
315c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
315d0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
315e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
315f0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
31600 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
31610 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31620 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
31630 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
31640 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
31650 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
31660 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
31670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31680 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
31690 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
316a0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
316b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
316c0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
316d0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
316e0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
316f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
31700 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31710 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
31720 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31730 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
31740 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
31750 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
31760 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31770 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31780 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
31790 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
317a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
317b0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
317c0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
317d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
317e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
317f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31800 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
31810 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
31820 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
31830 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
31840 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
31850 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
31860 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31870 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
31880 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
31890 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
318a0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
318b0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
318c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
318d0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
318e0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
318f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31900 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
31910 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31920 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
31930 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
31940 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
31950 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
31960 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
31970 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
31980 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  PI sqlite3 *sqli
31990 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
319a0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
319b0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
319c0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
319d0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
319e0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
319f0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
31a00 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
31a10 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
31a20 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
31a30 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
31a40 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
31a50 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
31a60 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
31a70 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
31a80 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
31a90 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
31aa0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
31ab0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
31ac0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
31ad0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
31ae0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
31af0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
31b00 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
31b10 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
31b20 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
31b30 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
31b40 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
31b50 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
31b60 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
31b70 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
31b80 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
31b90 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
31ba0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
31bb0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
31bc0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
31bd0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
31be0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
31bf0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
31c00 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
31c10 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
31c20 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
31c30 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
31c40 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
31c50 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
31c60 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
31c70 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
31c80 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
31c90 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
31ca0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
31cb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
31cc0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
31cd0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
31ce0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31cf0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
31d00 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
31d10 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
31d20 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
31d30 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
31d40 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
31d50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31d60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
31d70 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
31d80 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
31d90 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
31da0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
31db0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
31dc0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
31dd0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
31de0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
31df0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
31e00 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
31e10 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
31e20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31e30 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
31e40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
31e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31e60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
31e70 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
31e80 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
31e90 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
31ea0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
31eb0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
31ec0 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
31ed0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
31ee0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31ef0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
31f00 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
31f10 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
31f20 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
31f30 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
31f40 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
31f50 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
31f60 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
31f70 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
31f80 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
31f90 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
31fa0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
31fb0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
31fc0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
31fd0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
31fe0 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
31ff0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
32000 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
32010 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
32020 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
32030 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
32040 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
32050 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
32060 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
32070 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
32080 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
32090 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
320a0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
320b0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
320c0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
320d0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
320e0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
320f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
32100 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
32110 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
32120 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
32130 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
32140 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
32150 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
32160 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
32170 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
32180 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
32190 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
321a0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
321b0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
321c0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
321d0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
321e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
321f0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32200 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32210 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32220 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32230 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
32240 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
32250 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32260 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32270 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51  ext*, int N);.SQ
32280 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32290 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
322a0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
322b0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
322c0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
322d0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
322e0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
322f0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
32300 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
32310 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
32320 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
32330 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
32340 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
32350 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
32360 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
32370 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
32380 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
32390 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
323a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
323b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
323c0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
323d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
323e0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
323f0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
32400 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
32410 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
32420 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
32430 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
32440 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
32450 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
32460 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
32470 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
32480 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
32490 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
324a0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
324b0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
324c0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
324d0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
324e0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
324f0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
32500 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
32510 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
32520 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
32530 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
32540 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
32550 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
32560 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
32570 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
32580 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
32590 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
325a0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
325b0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
325c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
325d0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
325e0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
325f0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
32600 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
32610 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
32620 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
32630 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32640 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
32650 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
32660 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
32670 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
32680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
32690 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
326a0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
326b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
326c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
326d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
326e0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
326f0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
32700 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
32710 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
32720 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
32730 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
32740 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
32750 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
32760 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
32770 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
32780 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
32790 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
327a0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
327b0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
327c0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
327d0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
327e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
327f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32800 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
32810 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
32820 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
32830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32840 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
32850 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
32860 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
32870 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
32880 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
32890 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
328a0 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
328b0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
328c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
328d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
328e0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
328f0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
32900 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
32910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32930 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
32940 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
32950 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
32960 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
32970 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
32980 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
32990 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
329a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
329b0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
329c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
329d0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
329e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
329f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32a00 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
32a10 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
32a20 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
32a30 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
32a40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32a50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32a60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
32a70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
32a80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
32a90 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
32aa0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
32ab0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
32ac0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
32ad0 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
32ae0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
32af0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
32b00 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
32b10 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
32b20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32b30 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
32b40 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
32b50 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
32b60 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
32b70 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
32b80 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
32b90 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
32ba0 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
32bb0 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
32bc0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
32bd0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
32be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32bf0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
32c00 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
32c10 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
32c20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
32c30 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
32c40 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
32c50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32c60 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
32c70 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
32c80 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
32c90 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
32ca0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
32cb0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
32cc0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
32cd0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
32ce0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
32cf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32d00 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
32d10 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
32d20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
32d30 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
32d40 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
32d50 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
32d60 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
32d70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
32d80 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
32d90 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
32da0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32db0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
32dc0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
32dd0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
32de0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
32df0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
32e00 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
32e10 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
32e20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
32e30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
32e40 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
32e50 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
32e60 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
32e70 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
32e80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
32e90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
32ea0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
32eb0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
32ec0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
32ed0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
32ee0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
32ef0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
32f00 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
32f10 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
32f20 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
32f30 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
32f40 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
32f50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32f60 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
32f70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
32f80 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
32f90 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
32fa0 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
32fb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32fc0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
32fd0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
32fe0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
32ff0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
33000 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
33010 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
33020 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
33030 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
33040 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33050 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
33060 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
33070 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
33080 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
33090 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
330a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
330b0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
330c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
330d0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
330e0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
330f0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
33100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33110 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33120 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
33130 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
33140 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
33150 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
33160 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
33170 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
33180 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
33190 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
331a0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
331b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
331c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
331d0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
331e0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
331f0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
33200 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33210 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33220 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
33230 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33240 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
33250 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
33260 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33270 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
33280 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
33290 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
332a0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
332b0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
332c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
332d0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
332e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
332f0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
33300 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
33310 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
33320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33330 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33340 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
33350 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
33360 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
33370 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
33380 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
33390 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
333a0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
333b0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
333c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
333d0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
333e0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
333f0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
33400 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
33410 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
33420 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
33430 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
33440 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
33450 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
33460 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33470 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33480 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
33490 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
334a0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
334b0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
334c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
334d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
334e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
334f0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
33500 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33520 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
33530 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
33540 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
33550 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
33560 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
33570 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
33580 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
33590 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
335a0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
335b0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
335c0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
335d0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
335e0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
335f0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
33600 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
33610 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
33620 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
33630 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
33640 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
33650 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
33660 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
33670 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
33680 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
33690 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
336a0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
336b0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
336c0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
336d0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
336e0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
336f0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
33700 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
33710 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
33720 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
33730 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
33740 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
33750 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
33760 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
33770 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
33780 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
33790 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
337a0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
337b0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
337c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
337d0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
337e0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
337f0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
33800 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
33810 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
33820 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
33830 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
33840 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
33850 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
33860 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
33870 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
33880 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33890 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
338a0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
338b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
338c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
338d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
338e0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
338f0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
33900 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
33910 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
33920 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
33930 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
33940 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
33950 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
33960 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
33970 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
33980 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
33990 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
339a0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
339b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
339c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
339d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
339e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
339f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
33a00 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
33a10 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
33a20 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
33a30 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
33a40 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
33a50 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
33a60 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
33a70 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
33a80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33a90 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
33aa0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
33ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ac0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
33ad0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33ae0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
33af0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33b00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
33b10 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
33b20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33b30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33b40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
33b50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
33b60 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
33b70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
33b80 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
33b90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
33ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
33bb0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
33bc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
33bd0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
33be0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
33bf0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
33c00 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
33c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
33c20 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
33c30 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
33c40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
33c50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33c60 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
33c70 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
33c80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
33c90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33ca0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
33cb0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
33cc0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
33cd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
33ce0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
33cf0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
33d00 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
33d10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
33d20 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
33d30 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
33d40 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
33d50 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
33d60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33d70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
33d80 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
33d90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
33da0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
33db0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
33dc0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49  defined..*/.SQLI
33dd0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33de0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
33df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33e00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
33e10 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
33e20 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
33e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33e40 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
33e50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
33e60 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
33e70 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33e80 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
33e90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33ea0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
33eb0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33ed0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
33ee0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33ef0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
33f00 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33f10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33f20 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
33f30 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
33f40 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33f50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33f60 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
33f70 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
33f80 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33f90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
33fa0 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
33fb0 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  xt*, int);.SQLIT
33fc0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
33fd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
33fe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ff0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
34000 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
34010 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
34020 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
34030 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
34040 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
34050 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
34060 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34070 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
34080 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34090 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
340a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
340b0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
340c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
340d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
340e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
340f0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
34100 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34110 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34120 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
34130 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
34140 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
34150 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34160 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34170 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
34180 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
34190 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
341a0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
341b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
341c0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
341d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
341e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
341f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34200 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
34210 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
34220 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34230 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
34240 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
34250 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34260 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
34270 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
34280 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
34290 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
342a0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
342b0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
342c0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
342d0 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
342e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
342f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34300 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
34310 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34320 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
34330 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
34340 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
34350 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
34360 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34370 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
34380 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34390 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
343a0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
343b0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
343c0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
343d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
343e0 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
343f0 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
34400 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
34410 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
34420 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
34430 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
34440 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
34450 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
34460 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
34470 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
34480 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
34490 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
344a0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
344b0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
344c0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
344d0 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
344e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
344f0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
34500 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
34510 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
34520 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
34530 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
34540 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
34550 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
34560 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
34570 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
34580 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
34590 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
345a0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
345b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
345c0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
345d0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
345e0 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
345f0 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
34600 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
34610 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
34620 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
34630 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
34640 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
34650 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
34660 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
34670 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
34680 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
34690 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
346a0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
346b0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
346c0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
346d0 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
346e0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
346f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
34700 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
34710 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
34720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
34730 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
34740 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
34750 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
34760 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
34770 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
34780 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
34790 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
347a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
347b0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
347c0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
347d0 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
347e0 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
347f0 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
34800 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
34810 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
34820 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
34830 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
34840 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
34850 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
34860 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
34870 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34880 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
34890 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
348a0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
348b0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
348c0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
348d0 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
348e0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
348f0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
34900 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34910 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
34920 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
34930 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
34940 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
34950 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
34960 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
34970 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
34980 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
34990 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
349a0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
349b0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
349c0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
349d0 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
349e0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
349f0 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
34a00 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
34a10 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
34a20 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
34a30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
34a40 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
34a50 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
34a60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34a70 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
34a80 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
34a90 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
34aa0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
34ab0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
34ac0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34ad0 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
34ae0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
34af0 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
34b00 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
34b10 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
34b20 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
34b30 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
34b40 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
34b50 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
34b60 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
34b70 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
34b80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
34b90 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
34ba0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
34bb0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
34bc0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
34bd0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
34be0 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
34bf0 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
34c00 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
34c10 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
34c20 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
34c30 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
34c40 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
34c50 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
34c60 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
34c70 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
34c80 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
34c90 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
34ca0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
34cb0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
34cc0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
34cd0 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
34ce0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
34cf0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
34d00 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
34d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34d20 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34d30 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
34d40 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
34d50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
34d60 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
34d70 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
34d80 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
34d90 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
34da0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
34db0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34dc0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
34dd0 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
34de0 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
34df0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
34e00 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
34e10 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
34e20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
34e30 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
34e40 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
34e50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34e60 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
34e70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
34e80 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
34e90 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
34ea0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
34eb0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
34ec0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
34ed0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34ee0 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
34ef0 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
34f00 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
34f10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34f20 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
34f30 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
34f40 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
34f50 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
34f60 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
34f70 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
34f80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34f90 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
34fa0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
34fb0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
34fc0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
34fd0 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
34fe0 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
34ff0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
35000 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
35010 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
35020 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
35030 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
35040 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
35050 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
35060 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
35070 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
35080 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
35090 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
350a0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
350b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
350c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
350d0 31 36 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  16()]..*/.SQLITE
350e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
350f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35100 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
35110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
35120 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
35130 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
35140 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
35150 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
35160 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
35170 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
35180 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
35190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
351a0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
351b0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
351c0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
351d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
351e0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
351f0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
35200 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35210 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35220 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
35230 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
35240 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
35250 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
35260 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
35270 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
35280 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
35290 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
352a0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
352b0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
352c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
352d0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
352e0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
352f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
35300 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
35310 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
35320 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
35330 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
35340 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
35350 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
35360 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
35370 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
35380 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
35390 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
353a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
353b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
353c0 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
353d0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
353e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
353f0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
35400 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
35410 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
35420 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
35430 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
35440 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35450 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
35460 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
35470 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
35480 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
35490 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
354a0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
354b0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
354c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
354d0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
354e0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
354f0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
35500 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
35510 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
35520 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
35530 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
35540 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
35550 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
35560 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
35570 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
35580 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
35590 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
355a0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
355b0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
355c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
355d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
355e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
355f0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
35600 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35610 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
35620 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
35630 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
35640 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
35650 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
35660 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
35670 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
35680 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
35690 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
356a0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
356b0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
356c0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
356d0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
356e0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
356f0 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
35700 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
35710 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
35720 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
35730 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
35740 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
35750 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
35760 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
35770 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
35780 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
35790 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
357a0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
357b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
357c0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
357d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
357e0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
357f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
35800 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
35810 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
35820 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
35830 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
35840 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
35850 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
35860 68 61 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  har*).);.SQLITE_
35870 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
35880 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35890 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
358a0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
358b0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
358c0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
358d0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
358e0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48  .#ifdef SQLITE_H
358f0 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53  AS_CODEC./*.** S
35900 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
35910 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
35920 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
35930 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
35940 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
35950 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
35960 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
35970 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35980 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35990 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
359a0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
359b0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
359c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
359d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
359e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
359f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35a00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
35a10 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
35a20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
35a30 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
35a40 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
35a50 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
35a60 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
35a70 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
35a80 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
35a90 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
35aa0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
35ab0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
35ac0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
35ad0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
35ae0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
35af0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
35b00 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
35b10 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35b20 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35b30 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35b40 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35b50 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
35b60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35b70 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
35b80 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
35b90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
35ba0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
35bb0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
35bc0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
35bd0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
35be0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
35bf0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
35c00 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
35c10 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
35c20 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
35c30 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
35c40 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
35c50 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
35c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35c70 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
35c80 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
35c90 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
35ca0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
35cb0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
35cc0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
35cd0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
35ce0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
35cf0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
35d00 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
35d10 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
35d20 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
35d30 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
35d40 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
35d50 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c  ill work..*/.SQL
35d60 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
35d70 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
35d80 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
35d90 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
35da0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
35db0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
35dc0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
35dd0 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
35de0 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
35df0 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
35e00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
35e10 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
35e20 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
35e30 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
35e40 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
35e50 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
35e60 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
35e70 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
35e80 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
35e90 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
35ea0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35eb0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
35ec0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
35ed0 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
35ee0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
35ef0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
35f00 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
35f10 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
35f20 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
35f30 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
35f40 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
35f50 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
35f60 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
35f70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
35f80 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
35f90 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
35fa0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
35fb0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
35fc0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
35fd0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
35fe0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
35ff0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
36000 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
36010 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
36020 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
36030 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
36040 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
36050 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
36060 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
36070 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
36080 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
36090 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
360a0 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
360b0 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
360c0 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
360d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
360e0 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
360f0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36100 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
36110 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
36120 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
36130 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
36140 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
36150 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
36160 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
36170 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
36180 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
36190 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
361a0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
361b0 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
361c0 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
361d0 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
361e0 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
361f0 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
36200 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
36210 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
36220 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
36230 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
36240 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36250 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
36260 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
36270 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
36280 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
36290 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
362a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
362b0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
362c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
362d0 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
362e0 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
362f0 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
36300 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
36310 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36320 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
36330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36340 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
36350 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
36360 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
36370 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
36380 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
36390 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
363a0 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
363b0 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
363c0 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
363d0 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
363e0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
363f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
36400 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
36410 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36420 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
36430 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
36440 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36450 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
36460 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
36470 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
36480 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
36490 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
364a0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
364b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
364c0 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
364d0 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
364e0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
364f0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
36500 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
36510 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
36520 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36530 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
36540 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
36550 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
36560 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
36570 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
36580 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
36590 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
365a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
365b0 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
365c0 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
365d0 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
365e0 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
365f0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
36600 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
36610 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
36620 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
36630 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
36640 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
36650 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
36660 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
36670 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
36680 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
36690 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
366a0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
366b0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
366c0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
366d0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
366e0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
366f0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
36700 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  pen] or [sqlite3
36710 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65  _open_v2].  Othe
36720 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
36730 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
36740 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
36750 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
36760 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65  es may fail.  He
36770 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d  re is an.** exam
36780 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f  ple of how to do
36790 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20   this using C++ 
367a0 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73  with the Windows
367b0 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20   Runtime:.**.** 
367c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
367d0 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61  >.** LPCWSTR zPa
367e0 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74  th = Windows::St
367f0 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69  orage::Applicati
36800 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d  onData::Current-
36810 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  >.** &nbsp;     
36820 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d  TemporaryFolder-
36830 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a  >Path->Data();.*
36840 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26  * char zPathBuf&
36850 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31  #91;MAX_PATH + 1
36860 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74  &#93;;.** memset
36870 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69  (zPathBuf, 0, si
36880 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b  zeof(zPathBuf));
36890 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75  .** WideCharToMu
368a0 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c  ltiByte(CP_UTF8,
368b0 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a   0, zPath, -1, z
368c0 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28  PathBuf, sizeof(
368d0 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e  zPathBuf),.** &n
368e0 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e  bsp;     NULL, N
368f0 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33  ULL);.** sqlite3
36900 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20  _temp_directory 
36910 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
36920 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66  f("%s", zPathBuf
36930 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
36940 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c  ockquote>.*/.SQL
36950 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
36960 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
36970 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
36980 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
36990 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
369a0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
369b0 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
369c0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
369d0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
369e0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
369f0 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
36a00 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
36a10 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
36a20 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
36a30 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
36a40 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
36a50 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
36a60 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
36a70 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
36a80 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
36a90 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
36aa0 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
36ab0 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
36ac0 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
36ad0 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
36ae0 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
36af0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
36b00 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36b10 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
36b20 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
36b30 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
36b40 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
36b50 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
36b60 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
36b70 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
36b80 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
36b90 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
36ba0 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
36bb0 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
36bc0 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
36bd0 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
36be0 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
36bf0 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
36c00 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
36c10 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
36c20 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
36c30 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
36c40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c50 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
36c60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
36c70 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
36c80 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
36c90 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
36ca0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
36cb0 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
36cc0 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
36cd0 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
36ce0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
36cf0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
36d00 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
36d10 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
36d20 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
36d30 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
36d40 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
36d50 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
36d60 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
36d70 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
36d80 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
36d90 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
36da0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
36db0 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
36dc0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
36dd0 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
36de0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
36df0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
36e00 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
36e10 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
36e20 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
36e30 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
36e40 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36e50 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
36e60 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
36e70 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
36e80 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
36e90 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36ea0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
36eb0 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
36ec0 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
36ed0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
36ee0 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
36ef0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
36f00 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
36f10 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
36f20 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
36f30 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
36f40 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
36f50 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
36f60 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
36f70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
36f80 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
36f90 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
36fa0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
36fb0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
36fc0 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
36fd0 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
36fe0 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
36ff0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
37000 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
37010 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
37020 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
37030 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
37040 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
37050 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
37060 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
37070 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
37080 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
37090 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
370a0 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a  data_directory;.
370b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
370c0 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
370d0 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
370e0 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
370f0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
37100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
37110 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
37120 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37130 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
37140 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
37150 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37160 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
37170 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
37180 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
37190 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
371a0 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
371b0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
371c0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
371d0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
371e0 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
371f0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
37200 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
37210 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
37220 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
37230 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
37240 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
37250 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
37260 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
37270 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
37280 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
37290 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
372a0 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
372b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
372c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
372d0 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
372e0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
372f0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
37300 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
37310 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
37320 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
37330 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
37340 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
37350 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
37360 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
37370 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
37380 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
37390 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
373a0 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
373b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
373c0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
373d0 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
373e0 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
373f0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
37400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
37410 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
37420 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
37430 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37440 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37450 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
37460 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
37470 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
37480 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
37490 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
374a0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
374b0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
374c0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
374d0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
374e0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
374f0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
37500 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37510 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
37520 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
37530 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
37540 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
37550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
37560 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
37570 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
37580 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
37590 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
375a0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
375b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
375c0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
375d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
375e0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
375f0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
37600 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
37610 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
37620 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
37630 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  place..*/.SQLITE
37640 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71  _API sqlite3 *sq
37650 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
37660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
37670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37680 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65   Return The File
37690 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62  name For A Datab
376a0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
376b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
376c0 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c  3_db_filename(D,
376d0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
376e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
376f0 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  o a filename.** 
37700 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
37710 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f  database N of co
37720 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68  nnection D.  ^Th
37730 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
37740 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20  file.** has the 
37750 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66  name "main".  If
37760 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74   there is no att
37770 61 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e  ached database N
37780 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
37790 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  .** connection D
377a0 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65  , or if database
377b0 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72   N is a temporar
377c0 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  y or in-memory d
377d0 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a  atabase, then.**
377e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
377f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
37800 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  ** ^The filename
37810 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
37820 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  s function is th
37830 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a  e output of the.
37840 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  ** xFullPathname
37850 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
37860 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72  VFS].  ^In other
37870 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65   words, the file
37880 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  name.** will be 
37890 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
378a0 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68  name, even if th
378b0 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a  e filename used.
378c0 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ** to open the d
378d0 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c  atabase original
378e0 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20  ly was a URI or 
378f0 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
37900 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
37910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
37920 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
37930 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f  (sqlite3 *db, co
37940 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
37950 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
37960 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69  REF: Determine i
37970 66 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  f a database is 
37980 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20  read-only.**.** 
37990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f  ^The sqlite3_db_
379a0 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e  readonly(D,N) in
379b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
379c0 31 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73  1 if the databas
379d0 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63  e N.** of connec
379e0 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f  tion D is read-o
379f0 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20  nly, 0 if it is 
37a00 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d  read/write, or -
37a10 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a  1 if N is not.**
37a20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64   the name of a d
37a30 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65  atabase on conne
37a40 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49  ction D..*/.SQLI
37a50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37a60 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73  e3_db_readonly(s
37a70 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
37a80 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
37a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37aa0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
37ab0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37ac0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
37ad0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37ae0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37af0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
37b00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
37b10 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
37b20 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37b30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37b40 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
37b50 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
37b60 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
37b70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
37b80 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
37b90 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
37ba0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
37bb0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
37bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37bd0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
37be0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37bf0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
37c00 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
37c10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
37c20 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
37c30 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
37c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37c50 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
37c60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
37c70 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
37c80 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
37c90 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
37ca0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
37cb0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
37cc0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
37cd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
37ce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
37cf0 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
37d00 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
37d10 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
37d20 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
37d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37d40 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
37d50 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
37d60 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
37d70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
37d80 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
37d90 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37da0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
37db0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
37dc0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
37dd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
37de0 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
37df0 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
37e00 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37e10 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37e20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
37e30 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
37e40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
37e50 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
37e60 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
37e70 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
37e80 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
37e90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37ea0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
37eb0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
37ec0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
37ed0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
37ee0 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
37ef0 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
37f00 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
37f10 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
37f20 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
37f30 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
37f40 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
37f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
37f60 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
37f70 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
37f80 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
37f90 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
37fa0 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
37fb0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
37fc0 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
37fd0 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
37fe0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
37ff0 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
38000 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
38010 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
38020 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
38030 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
38040 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
38050 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
38060 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
38070 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
38080 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
38090 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
380a0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
380b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
380c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
380d0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
380e0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
380f0 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
38100 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
38110 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20   The commit and 
38120 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61  rollback hook ca
38130 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20  llbacks are not 
38140 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68  reentrant..** Th
38150 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65  e callback imple
38160 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
38170 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
38180 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
38190 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
381a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
381b0 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c  invoked the call
381c0 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  back.  Any actio
381d0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
381e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
381f0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
38200 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
38210 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
38220 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
38230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
38240 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
38250 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a  ed the commit.**
38260 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f   or rollback hoo
38270 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  k in the first p
38280 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  lace..** Note th
38290 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f  at running any o
382a0 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65  ther SQL stateme
382b0 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53  nts, including S
382c0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73  ELECT statements
382d0 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63  ,.** or merely c
382e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
382f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
38300 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
38310 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  )] will modify.*
38320 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
38330 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
38340 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
38350 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
38360 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
38370 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
38380 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
38390 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
383a0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
383b0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
383c0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
383d0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
383e0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
383f0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
38400 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
38410 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
38420 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
38430 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
38440 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
38450 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
38460 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
38470 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
38480 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
38490 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
384a0 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
384b0 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
384c0 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
384d0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
384e0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
384f0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
38500 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
38510 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
38520 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
38530 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
38540 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
38550 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
38560 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
38570 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
38580 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
38590 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
385a0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
385b0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
385c0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
385d0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
385e0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
385f0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
38600 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
38610 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
38620 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
38630 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
38640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
38650 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
38660 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
38670 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38680 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
38690 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
386a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
386b0 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
386c0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
386d0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
386e0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
386f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
38700 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
38710 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
38720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38730 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
38740 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
38750 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
38760 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
38770 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
38780 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
38790 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
387a0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
387b0