/ Hex Artifact Content
Login

Artifact 26b6aa6a1825b97c0fa16ce14fc657be00c299f6:


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 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5b90: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5ba0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5bb0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5bc0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5bd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5be0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5bf0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5c00: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5c30: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5c40: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5c50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5c60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5c70: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c90: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ca0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5cb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ce0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5d00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5d50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5d90: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5da0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5dd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5de0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5e20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5e50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5e60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5e70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ec0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5ef0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5f40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5f70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5f80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5fb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5fc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5ff0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6070: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
60b0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
60c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6100: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6140: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6150: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6160: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
61a0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
61b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
61f0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6240: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6250: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6260: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6270: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6280: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6290: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
62a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
62b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
62c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
62d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
62e0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
62f0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
6300: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6310: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6320: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6330: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6340: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6350: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6360: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6370: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6390: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
63a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
63b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
63e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
63f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6400: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6410: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6420: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6430: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6440: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6450: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6460: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6490: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
64a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
64b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
64c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
64d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
64e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
64f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6500: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6510: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6520: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6530: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6540: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6550: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6560: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6570: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6580: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6590: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
65a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
65b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
65c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
65d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
65e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
65f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6600: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6610: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6620: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6630: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6640: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6660: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6670: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6680: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6690: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
66a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
66b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
66c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
66d0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
66f0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6700: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
6710: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6720: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6730: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6740: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6750: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6760: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6770: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6780: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6790: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
67a0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
67b0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
67c0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
67d0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
67e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6800: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6820: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6830: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6840: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6860: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6870: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6880: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6890: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
68c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68e0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
68f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6900: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6910: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6930: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6950: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6980: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
69e0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
69f0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a50: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6a60: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6a80: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6a90: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6ae0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6af0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6b00: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6b10: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6b20: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6b30: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6b40: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6b50: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6b60: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6b70: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6b80: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6b90: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ba0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6bb0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6bc0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6bd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6be0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c00: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6c30: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6c40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6c50: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6c70: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6c80: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6c90: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6ca0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6cb0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6cc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cd0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6ce0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6cf0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6d00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6d20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6d30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6d40: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6d50: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6d60: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6d70: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6d80: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6d90: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6da0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6db0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6dc0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6dd0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6de0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6df0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e00: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6e10: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6e20: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6e30: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6e40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6e50: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e60: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6e70: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6e80: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e90: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6ea0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6eb0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6ec0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6ed0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6ee0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6ef0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6f00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f10: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6f20: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f30: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6f40: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6f50: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6f60: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6f70: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6f80: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6f90: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6fa0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6fb0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6fc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6fd0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fe0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6ff0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7000: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7010: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7020: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7030: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7040: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7050: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7060: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7070: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7080: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7090: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
70a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
70b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
70c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
70d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
70e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
70f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7100: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7110: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7120: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7130: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7140: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7150: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7160: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7180: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7190: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
71b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
71c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
71d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
71e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
71f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7200: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7210: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7220: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7240: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7250: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7260: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7270: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7280: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7290: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
72a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
72b0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
72c0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
72d0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
72e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
72f0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7300: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7310: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7340: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7350: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7360: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7370: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7380: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7390: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
73a0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
73b0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
73c0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
73d0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
73e0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
73f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7400: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7410: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7420: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7430: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7440: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7450: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7460: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7470: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7480: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7490: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
74a0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
74b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
74c0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
74d0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
74e0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7500: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7510: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7520: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7530: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7540: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7550: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7560: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7570: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7580: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7590: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
75a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
75b0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
75c0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
75d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
75e0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
75f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7600: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7610: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7620: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7640: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7650: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7660: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7670: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7680: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7690: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
76a0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
76b0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
76c0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
76d0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
76e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
76f0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7700: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7710: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7720: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7730: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7740: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7750: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7760: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7770: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7780: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7790: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
77a0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
77b0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
77c0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
77d0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
77e0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
77f0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7810: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7820: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7830: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7840: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7850: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7860: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7870: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7880: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7890: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
78a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
78b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
78c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
78d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
78e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7900: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7910: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7920: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7950: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7960: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7970: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7980: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7990: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
79a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
79b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
79c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
79d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
79e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
79f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7a00: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7a10: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7a20: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7a30: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7a40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7a50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7a60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7a70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7a80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7a90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7aa0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7ab0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7ac0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7ad0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7ae0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7af0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7b20: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7b30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7b50: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7b60: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7b70: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7b80: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7b90: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ba0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7bb0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7bc0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7bd0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7be0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7bf0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7c00: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7c10: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7c20: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7c30: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7c40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7c50: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7c60: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7c70: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7c80: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7c90: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7ca0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7cb0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7cc0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7cd0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7ce0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7cf0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7d00: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7d10: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7d20: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7d30: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7d40: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7d50: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7d60: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
7d70: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
7d80: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
7d90: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
7da0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
7db0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
7dc0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
7dd0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7de0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
7df0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
7e00: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
7e10: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
7e20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e30: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
7e40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
7e50: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
7e60: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
7e70: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
7e80: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
7e90: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
7ea0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
7eb0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
7ec0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
7ed0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
7ee0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
7ef0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
7f00: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
7f10: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
7f20: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
7f30: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
7f40: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
7f50: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
7f60: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7f70: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
7f80: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
7f90: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
7fa0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
7fb0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
7fc0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
7fd0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7fe0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ff0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8010: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8070: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8080: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8090: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
80b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
80c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
80e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8110: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8130: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
8140: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8170: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8180: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8190: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
81a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
81b0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
81c0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
81d0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
81e0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
81f0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8200: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8210: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8220: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8230: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8240: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8250: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8260: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8270: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8280: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8290: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
82a0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
82b0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
82c0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
82d0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
82e0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
82f0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8300: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8310: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8320: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8330: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8340: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8350: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8360: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8370: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8380: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8390: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
83a0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
83b0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
83c0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
83d0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
83e0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
83f0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8400: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8410: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8420: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8430: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8440: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8450: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8460: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8470: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8480: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8490: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
84a0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
84b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
84c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
84d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
84e0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
84f0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8500: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8510: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8520: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8530: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8540: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8550: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8560: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8580: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8590: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
85a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
85b0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
85c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
85e0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
85f0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8600: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8640: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8650: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8660: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8670: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8680: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8690: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
86a0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
86b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86c0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86d0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8700: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8710: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8720: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8730: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8740: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8750: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8760: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8770: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8780: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8790: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
87a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
87b0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
87c0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
87e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
87f0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8800: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8810: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8820: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8830: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8840: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8860: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8870: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8880: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8890: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
88a0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
88b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
88c0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
88d0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
88e0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
88f0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8900: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8910: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8920: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8930: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8940: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8950: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8960: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8970: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8980: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
89a0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
89b0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
89c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
89d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
89e0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
89f0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8a00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8a10: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8a20: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8a30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8a40: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8a50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8a60: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8a70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8a80: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8a90: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8ab0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ac0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8ad0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8ae0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8af0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b00: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8b10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8b20: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8b30: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8b40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8b60: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8b70: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8b90: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8ba0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8bb0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8bc0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8bd0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8be0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8bf0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c00: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8c10: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8c20: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8c30: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8c40: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8c50: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8c60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8c70: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8c80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8c90: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ca0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8cb0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8cc0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8cd0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8cf0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d00: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8d10: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8d20: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8d30: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8d40: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8d50: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8d60: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8d70: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8d80: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8d90: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8da0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8db0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8dc0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8dd0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8de0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8df0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8e10: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8e20: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8e30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e40: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8e50: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8e60: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8e70: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8e80: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8e90: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8ea0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8eb0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8ec0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8ed0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8ee0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8ef0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f00: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8f10: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8f20: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8f30: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8f40: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8f50: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8f60: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8f70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8f80: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8f90: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8fa0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8fb0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8fc0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8fd0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8fe0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8ff0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9000: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9010: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9020: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9040: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9050: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9060: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9070: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9080: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9090: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
90a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
90b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
90c0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
90d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
90e0: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
90f0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9100: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9110: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9120: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9130: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9140: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9150: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9160: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9180: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9190: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
91a0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
91b0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
91c0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
91d0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
91e0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
91f0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9200: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9210: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9220: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9230: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9240: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9250: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9260: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9270: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9280: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9290: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
92a0: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
92b0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
92c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
92d0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
92e0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
92f0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9300: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9310: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9320: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9340: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9350: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9360: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9370: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9380: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9390: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
93a0: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
93b0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
93c0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
93d0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
93e0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
93f0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9400: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9410: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9420: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9430: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9440: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9450: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9460: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9470: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9480: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9490: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
94a0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
94b0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
94c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
94d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
94e0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
94f0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9510: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9520: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9530: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9540: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9550: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9560: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9570: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9580: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9590: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
95a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
95b0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
95c0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
95d0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
95e0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
95f0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9600: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9610: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9620: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9630: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9640: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9650: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9660: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9670: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9680: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9690: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
96a0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
96b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
96c0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
96d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
96e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96f0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9700: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9710: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9720: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9730: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9740: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9750: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9760: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9770: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9780: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9790: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
97a0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
97b0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
97c0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
97d0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
97e0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
97f0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9800: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9810: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9820: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9830: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9840: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9850: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9860: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9870: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9880: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9890: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
98a0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
98b0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
98c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
98d0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
98e0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
98f0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9900: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9910: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9920: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9930: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9940: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9950: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9960: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9970: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9980: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9990: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
99a0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
99b0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
99c0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
99d0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
99e0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
99f0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9a00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9a10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9a20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9a30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9a40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9a50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9a60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9a70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9a80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9a90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9aa0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9ab0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9ac0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9ad0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9ae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9af0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9b20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9b40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9b50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9b60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9b70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9b80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9b90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9ba0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9bb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9bc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9bd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9be0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9bf0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9c00: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9c10: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9c20: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9c30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9c40: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9c50: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9c60: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9c70: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9c80: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9c90: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9ca0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9cb0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9cc0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9cd0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9ce0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9cf0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9d00: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9d10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9d20: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9d30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9d40: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9d50: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d60: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9d70: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9d80: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9d90: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9da0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9db0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9dc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9dd0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9de0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9df0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9e00: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9e10: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9e20: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9e30: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9e40: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9e50: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9e60: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9e70: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9e80: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9e90: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9ea0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
9eb0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9ec0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ed0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9ee0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9f00: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9f10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9f20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9f30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9f40: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9f50: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9f60: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9f70: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9f80: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9f90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9fa0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9fb0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9fc0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9fd0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9fe0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9ff0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a000: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a010: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a020: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a030: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a040: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a050: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a060: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a070: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a080: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a090: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a0a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a0b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a0c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a0d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a0e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a0f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a100: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a110: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a120: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a130: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a140: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a150: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a160: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a170: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a180: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a190: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a1a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a1b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a1c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a1d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a1e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a1f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a200: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a210: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a220: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a240: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a250: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a260: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a270: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a280: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a290: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a2a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a2b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a2c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a2d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a2e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a2f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a300: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a310: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a320: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a330: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a340: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a350: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a360: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a370: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a380: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a390: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a3a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a3b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a3c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a3d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a3e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a3f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a400: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a410: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a420: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a430: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a440: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a450: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a460: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a470: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a480: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a490: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a4a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a4b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a4c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a4d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a4e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a4f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a500: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a510: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a520: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a530: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a540: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a550: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a560: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a570: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a580: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a590: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a5a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a5b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a5c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a5d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a5e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a5f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a600: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a610: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a620: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a630: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a640: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a650: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a660: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a670: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a680: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a690: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a6a0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a6b0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a6c0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a6d0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a6e0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a6f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a700: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a710: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a730: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a740: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a750: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a760: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a770: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a780: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a790: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a7a0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a7b0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a7c0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a7d0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a7e0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a7f0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a800: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a810: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a820: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a830: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a840: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a850: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a860: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a870: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a880: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a890: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a8a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a8b0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a8c0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a8d0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a8e0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a8f0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a900: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a910: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a920: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a930: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a940: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a950: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a960: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a970: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a980: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a990: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a9a0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a9b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a9c0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a9d0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a9e0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a9f0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
aa00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
aa10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
aa20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
aa30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
aa40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
aa50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
aa90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
aaa0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
aab0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
aac0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
aad0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
aae0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
aaf0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ab10: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
ab20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab30: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
ab40: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
ab50: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
ab60: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
ab70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
ab80: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
ab90: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
aba0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
abb0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
abc0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
abd0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
abe0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
abf0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
ac00: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
ac10: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
ac20: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
ac30: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
ac40: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
ac50: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
ac60: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
ac70: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
ac80: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
ac90: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
aca0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
acb0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
acc0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
acd0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
ace0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
acf0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
ad00: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
ad10: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
ad20: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
ad30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
ad40: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
ad50: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
ad60: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
ad70: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
ad80: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
ad90: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
ada0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
adb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
adc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
add0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
ade0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
adf0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
ae00: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ae10: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
ae20: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
ae30: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
ae40: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ae50: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
ae60: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
ae70: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
ae80: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
ae90: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aea0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
aeb0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
aec0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aed0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aee0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aef0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
af00: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
af10: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
af20: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
af30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
af40: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
af50: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
af60: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
af70: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
af80: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
af90: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
afa0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
afc0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
afe0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
aff0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b000: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b010: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b020: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b030: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b040: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b050: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b060: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b070: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b080: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b090: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b0a0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b0b0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b0c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b0d0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b0e0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b0f0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b100: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b110: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b120: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b130: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b140: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b150: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b160: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b170: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b180: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b190: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b1a0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b1b0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b1c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b1d0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b1e0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b1f0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b200: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b220: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b230: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b240: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b250: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b260: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b270: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b280: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b290: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b2a0: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b2b0: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b2e0: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b2f0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b300: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b310: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b320: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b330: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b340: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
b350: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
b360: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
b370: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
b380: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
b390: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
b3a0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
b3b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
b3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b3d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
b3e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3f0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
b400: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
b410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
b420: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
b430: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
b440: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
b450: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
b460: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
b470: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
b480: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
b490: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
b4a0: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
b4b0: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
b4c0: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
b4d0: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
b4f0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
b500: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b510: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b520: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
b530: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
b540: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
b550: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
b560: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b570: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
b580: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
b590: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
b5a0: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
b5b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
b5c0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
b5d0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
b5e0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
b5f0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
b600: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
b610: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
b620: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  ned..**.** </ul>
b630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b640: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
b650: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b660: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b670: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
b680: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
b690: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b6a0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
b6b0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
b6c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b700: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b730: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
b740: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
b750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b760: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
b770: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
b7a0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
b7d0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b7f0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
b800: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
b810: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
b820: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
b830: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
b850: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
b860: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b880: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b890: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b8b0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
b8c0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b8e0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
b8f0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b910: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
b920: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b940: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
b950: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b980: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
ba00: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
ba30: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f  NDLE       23../
ba40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ba50: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
ba60: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
ba70: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
ba80: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
ba90: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
baa0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
bab0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
bac0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
bad0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
bae0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
baf0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
bb00: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
bb10: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
bb20: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
bb30: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
bb40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bb50: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
bb60: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
bb70: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
bb80: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
bb90: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
bba0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
bbb0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
bbc0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
bbd0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bbe0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
bbf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bc00: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bc10: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
bc20: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
bc30: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
bc40: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
bc50: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
bc60: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
bc70: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
bc80: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
bc90: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
bca0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
bcb0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
bcc0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
bcd0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
bce0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
bcf0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
bd00: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
bd10: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
bd20: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
bd30: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
bd40: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
bd50: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
bd60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
bd70: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
bd80: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
bd90: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
bda0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
bdb0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
bdc0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
bdd0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
bde0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
bdf0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
be00: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
be10: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
be20: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
be30: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
be40: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
be50: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
be60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
be70: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
be80: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
be90: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
bea0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
beb0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
bec0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
bed0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
bee0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
bef0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
bf00: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
bf10: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
bf20: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
bf30: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
bf40: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
bf50: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
bf60: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
bf70: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
bf80: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
bf90: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
bfa0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
bfb0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
bfc0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
bfd0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
bfe0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
bff0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c000: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c010: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c030: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c050: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c060: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c070: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c080: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c090: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c0a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c0b0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
c0c0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
c0d0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
c0e0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
c0f0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
c100: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
c110: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
c120: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
c130: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c140: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
c150: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
c160: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
c170: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
c180: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
c190: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
c1a0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
c1b0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
c1c0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
c1d0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
c1e0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
c1f0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
c200: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
c210: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c220: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
c230: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
c240: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
c250: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c260: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
c270: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
c280: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
c290: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
c2a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
c2b0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
c2c0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
c2d0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
c2e0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
c2f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c300: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
c310: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
c320: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
c330: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
c340: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
c350: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
c360: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
c370: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
c380: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
c390: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
c3a0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
c3b0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
c3c0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
c3d0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
c3e0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
c3f0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
c400: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
c410: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
c420: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
c430: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
c440: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
c450: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
c460: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
c470: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
c480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c490: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c4a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
c4b0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
c4c0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
c4d0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
c4e0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
c4f0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
c500: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
c510: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
c520: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
c530: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
c540: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
c550: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
c560: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c570: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
c580: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
c590: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c5a0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
c5b0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
c5c0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
c5d0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
c5e0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
c5f0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
c600: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
c610: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
c620: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
c630: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
c640: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
c650: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
c660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c670: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c680: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c690: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c6a0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c6b0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c6c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c6d0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c6e0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c6f0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c700: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c710: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c720: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c730: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c740: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c750: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c760: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c770: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c780: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c790: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c7a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c7b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c7c0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c7d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c800: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c820: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c840: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c850: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c860: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c880: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c890: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c8a0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c8b0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c8c0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c8d0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c8e0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c8f0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c900: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c910: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c920: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c930: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c940: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c950: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c960: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c970: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c980: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c990: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c9a0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c9b0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c9c0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c9d0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c9e0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c9f0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
ca00: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
ca10: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
ca20: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ca30: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ca40: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ca50: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
ca60: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ca70: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
ca80: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ca90: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
caa0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
cab0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
cac0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cad0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cae0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
caf0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
cb00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
cb10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cb20: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
cb30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cb40: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
cb50: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cb60: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb70: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
cb80: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cb90: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
cba0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
cbb0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cbc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cbd0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
cbe0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
cbf0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
cc00: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
cc10: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
cc20: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
cc30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
cc40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc50: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
cc60: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
cc70: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
cc80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
cc90: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
cca0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
ccb0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
ccc0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
ccd0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
cce0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
ccf0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
cd00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
cd10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
cd20: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
cd30: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
cd40: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
cd50: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
cd60: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
cd70: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
cd80: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
cd90: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
cda0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
cdb0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
cdc0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
cdd0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
cde0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
cdf0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
ce00: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
ce10: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
ce20: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
ce30: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
ce40: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
ce50: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
ce60: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
ce70: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ce80: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ce90: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
cea0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ceb0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
cec0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ced0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
cee0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
cef0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
cf00: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
cf10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
cf20: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
cf30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
cf40: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
cf50: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
cf60: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
cf70: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
cf80: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
cf90: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
cfa0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
cfb0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
cfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
cfd0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
cfe0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
cff0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d000: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d010: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d020: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d030: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d040: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d050: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d060: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d070: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d080: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d090: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d0a0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d0b0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
d0c0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
d0d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d0e0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
d0f0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d100: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
d110: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
d120: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d130: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
d140: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d150: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
d160: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
d170: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
d180: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
d190: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
d1a0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
d1b0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
d1c0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
d1d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
d1e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
d1f0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d210: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
d220: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
d230: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
d240: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
d250: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d260: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
d270: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
d280: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
d290: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
d2a0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
d2b0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
d2c0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
d2d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d2e0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
d2f0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
d300: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
d310: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
d320: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
d330: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
d340: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d350: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
d360: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
d370: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d380: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
d390: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
d3a0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
d3b0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
d3c0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
d3d0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
d3e0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
d3f0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
d400: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d410: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
d420: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
d430: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
d440: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
d450: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
d460: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
d470: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
d480: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
d490: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
d4a0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
d4b0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
d4c0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
d4d0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
d4e0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
d4f0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
d500: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
d510: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
d520: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
d530: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
d540: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
d550: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
d560: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
d570: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
d580: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
d590: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
d5a0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d5b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
d5c0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
d5d0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
d5e0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
d5f0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
d600: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
d610: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
d620: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
d630: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
d640: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
d650: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d660: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d670: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d680: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d690: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d6a0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d6b0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d6c0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d6d0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d6e0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d6f0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d700: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d710: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d720: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d730: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d740: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d750: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d760: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d770: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d780: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d790: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d7a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d7b0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d7c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d7d0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d7e0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d7f0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d800: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d810: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d820: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d830: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d840: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d850: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d860: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d870: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d880: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d890: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d8a0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d8b0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d8c0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d8d0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d8e0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d8f0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d900: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d910: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d920: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d930: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d940: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d950: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d960: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d970: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d980: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d990: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d9a0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d9b0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d9c0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d9d0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d9e0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d9f0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
da00: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
da10: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
da20: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
da30: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
da40: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
da50: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
da60: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
da70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
da80: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
da90: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
daa0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
dab0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
dac0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dad0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
dae0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
daf0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
db00: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
db10: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
db20: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
db30: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
db40: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
db50: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
db60: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
db70: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
db80: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
db90: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
dba0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
dbb0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
dbc0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
dbd0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbe0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
dbf0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
dc00: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
dc10: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
dc20: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
dc30: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
dc40: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
dc50: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
dc60: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
dc70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dc80: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
dc90: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
dca0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
dcb0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
dcc0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
dcd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dce0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dcf0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
dd00: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
dd10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd30: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
dd40: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
dd50: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
dd60: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
dd70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd80: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
dd90: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
dda0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
ddd0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
dde0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
ddf0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
de00: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
de10: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
de20: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
de30: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
de40: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
de50: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
de60: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
de70: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
de80: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
de90: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
deb0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
dec0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ded0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
dee0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
def0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
df00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
df10: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
df20: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
df30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
df40: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
df50: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
df60: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
df70: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
df80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
df90: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
dfa0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
dfb0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
dfc0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
dfd0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
dfe0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
dff0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e000: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e010: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e020: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e030: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e040: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e050: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e060: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e070: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e080: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e090: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e0b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e0c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e0d0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e0e0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
e0f0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
e100: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e120: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e130: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
e140: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
e150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e160: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e170: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e180: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e190: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e1a0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
e1b0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e1c0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
e1d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
e1e0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
e1f0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
e200: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
e210: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
e220: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
e230: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
e240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e250: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e260: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
e270: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e280: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
e2a0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
e2b0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
e2c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
e2d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
e2e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
e2f0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
e300: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
e310: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
e320: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
e330: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
e340: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
e350: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
e360: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
e370: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
e380: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
e390: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
e3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e3b0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
e3c0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e3d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
e3e0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
e3f0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
e400: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
e410: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
e420: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
e430: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
e440: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
e450: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
e460: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
e470: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e480: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
e490: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
e4a0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
e4b0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e4c0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
e4d0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
e4e0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
e4f0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
e500: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
e510: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e520: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
e530: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e540: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e550: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
e560: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e570: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
e580: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
e590: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
e5a0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
e5b0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
e5c0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
e5d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e5e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e5f0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
e600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e610: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
e620: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
e630: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
e650: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e660: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e670: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e680: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e690: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e6a0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e6b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e6c0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e6d0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e6e0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e6f0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e700: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e710: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e720: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e730: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e740: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e750: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e760: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e770: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e780: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e790: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e7b0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e7c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e7d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e7e0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e7f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e800: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e810: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e820: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e830: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e840: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e850: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e860: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e870: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e880: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e890: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e8a0: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e8b0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e8c0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e8d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e8e0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e8f0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e900: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e910: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e920: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e930: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e940: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e950: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e960: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e970: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e980: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e9a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9c0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9e0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e9f0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
ea00: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
ea10: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
ea20: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ea30: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
ea40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
ea50: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
ea60: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
ea70: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
ea80: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
ea90: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
eaa0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
eab0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
eac0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
ead0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
eae0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
eaf0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
eb00: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
eb10: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
eb20: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
eb30: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
eb40: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
eb50: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
eb60: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
eb70: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
eb80: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
eb90: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
eba0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ebb0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
ebc0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
ebd0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
ebe0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
ebf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
ec00: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ec10: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
ec20: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
ec30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
ec40: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
ec50: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
ec60: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
ec70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
ec80: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
ec90: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
eca0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
ecb0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
ecc0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
ecd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
ece0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
ecf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
ed00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
ed10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ed20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
ed40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
ed50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
ed60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
ed70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
eda0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
edb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
edc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
edd0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
ede0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
edf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee00: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
ee10: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
ee20: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
ee30: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ee40: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
ee70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ee80: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
ee90: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
eea0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
eeb0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
eec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eed0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
eee0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
eef0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef00: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ef10: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ef20: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
ef30: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
ef70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ef80: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
ef90: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
efa0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
efb0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
efc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
efd0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
efe0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
eff0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f000: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f010: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f030: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f040: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f050: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f060: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f070: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f080: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f090: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f0a0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f0b0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
f0e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f0f0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
f100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f110: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
f120: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f130: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
f140: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f150: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f160: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
f170: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
f180: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
f190: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
f1a0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
f1b0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
f1c0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
f1d0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
f1e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
f1f0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
f200: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
f210: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
f220: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
f230: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
f240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
f250: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
f280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
f290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
f2a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
f2b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
f2c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
f2d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
f2e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f2f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
f310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
f330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
f350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
f360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
f370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
f380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
f3a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
f3b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
f3c0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
f3d0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f3e0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
f3f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f400: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
f410: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
f420: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
f430: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f440: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f450: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
f460: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f470: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
f480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f490: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
f4a0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
f4b0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f4c0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
f4d0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
f4e0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
f4f0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
f500: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
f510: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f520: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
f530: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
f540: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f550: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f560: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
f570: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
f580: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
f590: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
f5a0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
f5b0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
f5c0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
f5d0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
f5e0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f5f0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
f600: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
f610: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
f620: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
f630: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
f640: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
f650: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
f660: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f670: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f680: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f690: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f6a0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f6b0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f6c0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f6d0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f6e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f6f0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f700: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f710: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f720: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f730: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f740: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f750: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f760: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f770: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f780: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f790: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f7a0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f7b0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f7c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f7d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f7e0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f7f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f800: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f810: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f820: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f830: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f840: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f850: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f860: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f870: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f880: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f890: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8a0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f8b0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f8c0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f8d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f8e0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f8f0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f900: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f910: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f920: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f930: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f940: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f950: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f960: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f970: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f980: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f990: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f9a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f9b0: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f9c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f9d0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f9e0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f9f0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
fa00: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
fa10: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
fa20: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
fa30: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
fa40: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
fa50: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
fa60: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
fa70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fa90: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
faa0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
fab0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fac0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
fad0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
fae0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
faf0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
fb00: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
fb10: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
fb20: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
fb30: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
fb40: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
fb50: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
fb60: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
fb70: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
fb80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
fb90: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fba0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
fbb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fbc0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
fbd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
fbe0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fbf0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fc00: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fc10: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
fc20: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fc30: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
fc40: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
fc50: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
fc60: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
fc70: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
fc80: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
fc90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
fca0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
fcb0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
fcc0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
fcd0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
fce0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
fcf0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
fd00: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
fd10: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
fd20: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
fd30: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
fd40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd60: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
fd70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
fd80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
fd90: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
fda0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
fdb0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
fdc0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
fdd0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
fde0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
fdf0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
fe00: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
fe10: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
fe20: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
fe30: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
fe40: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
fe50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
fe60: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
fe70: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
fe80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe90: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
fea0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
feb0: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
fec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fed0: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
fee0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
fef0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
ff00: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
ff10: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
ff20: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ff30: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
ff40: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ff50: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ff60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff70: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ff80: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ff90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ffa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ffb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ffc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ffd0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ffe0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fff0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10000 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10010 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10020 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10030 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10040 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10050 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10060 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10080 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10090 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
100a0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
100b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
100c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100d0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
100e0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
100f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10100 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10110 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10120 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10130 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10140 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10150 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10170 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10190 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
101a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
101b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
101c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
101d0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
101e0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
101f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10200 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10220 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10230 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10250 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10260 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10270 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10290 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
102a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
102b0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
102c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
102d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
102e0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
102f0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10300 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10310 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10320 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10330 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10340 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10350 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10370 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10380 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
103a0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
103b0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
103c0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
103d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
103e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
103f0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10400 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10410 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10420 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10430 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10440 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10450 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10460 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10470 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10480 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10490 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
104a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
104b0 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
104c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
104d0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
104e0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
104f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10500 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10510 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10520 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10530 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10540 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10550 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10570 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10580 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
105a0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
105b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105c0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
105d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
105e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105f0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10600 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10610 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10620 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10630 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10660 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10670 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10690 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
106a0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
106b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
106c0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
106d0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
106e0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
106f0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10700 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10710 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10720 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10730 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10740 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10750 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10760 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10770 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10780 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10790 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
107a0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
107b0 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
107c0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
107d0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
107e0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
107f0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10800 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10810 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10820 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10830 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10840 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10850 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10860 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10870 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10880 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10890 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
108a0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
108b0 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
108c0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
108d0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
108e0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
108f0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10900 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10910 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10920 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10930 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10940 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10950 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10960 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10970 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10980 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10990 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
109a0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
109b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
109c0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
109d0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
109e0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
109f0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10a00 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10a10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10a20 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10a30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10a40 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10a50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10a60 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10a70 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10a80 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10a90 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10aa0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10ab0 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10ac0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10ad0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10ae0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10af0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10b00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b10 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10b30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10b40 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10b50 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10b60 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10b70 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10b80 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10b90 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10ba0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10bb0 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10bc0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10bd0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10be0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10bf0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10c00 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10c10 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
10c20 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
10c30 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
10c40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10c50 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
10c60 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10c70 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10c80 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10c90 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10ca0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10cb0 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10cc0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10cd0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10ce0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10cf0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
10d00 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
10d10 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
10d20 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
10d30 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
10d40 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
10d50 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
10d60 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10d70 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
10d80 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
10d90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10da0 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
10db0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
10dc0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
10dd0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
10de0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
10df0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
10e00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
10e10 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
10e20 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
10e30 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
10e40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
10e50 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
10e60 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
10e70 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
10e80 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
10e90 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
10ea0 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
10eb0 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
10ec0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10ed0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
10ee0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
10ef0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
10f00 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
10f10 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
10f20 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
10f30 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
10f40 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
10f50 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10f60 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
10f70 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
10f80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
10f90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
10fa0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fb0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
10fc0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
10fd0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
10fe0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
10ff0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11000 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11010 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11030 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11050 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11060 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11070 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11080 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11090 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
110a0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
110b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
110c0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
110d0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
110e0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
110f0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11100 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11120 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11130 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11140 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11150 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11160 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11170 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11180 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
111a0 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
111b0 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
111c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
111d0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
111e0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
111f0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11200 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11210 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11220 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11230 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11240 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11250 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11260 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11270 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11280 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11290 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
112a0 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
112b0 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
112c0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
112d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
112e0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
112f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11300 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11310 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11320 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11330 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11340 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11350 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11370 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11380 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11390 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
113a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
113b0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
113c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
113d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113e0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
113f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11400 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11410 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11430 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11440 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11460 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11470 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11480 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
114a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
114b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
114c0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
114d0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
114e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
114f0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11500 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11510 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11520 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11530 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11540 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11550 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11560 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11570 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11580 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11590 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
115a0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
115b0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
115c0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
115d0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
115f0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11600 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11610 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11620 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11640 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11650 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11660 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11670 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11680 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11690 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
116a0 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
116b0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
116c0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
116d0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
116e0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
116f0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11700 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11710 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11720 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
117a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
117b0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
117c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
117d0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
117e0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
117f0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11800 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11810 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11820 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11830 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11840 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11850 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11870 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
118a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
118b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
118c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
118d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
118e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
118f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11900 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11910 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11920 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11930 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11940 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11950 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11970 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11980 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11990 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
119a0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
119b0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
119c0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
119d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
119e0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
119f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a00 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11a10 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11a20 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11a30 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11a40 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11a50 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11a60 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11a70 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11a80 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11a90 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ab0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11ac0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11ad0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ae0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11b00 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11b10 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11b20 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11b30 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11b40 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11b50 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11b60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11b70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11b80 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11b90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11ba0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11bb0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11bc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11bd0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
11be0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11bf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11c00 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
11c10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c20 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
11c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11c40 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11c50 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11c60 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11c70 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11c90 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
11ca0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
11cb0 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
11cc0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
11cd0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
11ce0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
11cf0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11d20 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11d30 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
11d40 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
11d50 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
11d60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
11d80 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
11d90 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
11da0 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
11db0 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
11dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dd0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11df0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
11e00 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
11e10 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
11e20 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11e30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
11e40 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
11e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
11e60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
11e70 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
11e80 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11eb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11ec0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ed0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11ee0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11ef0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
11f10 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
11f20 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11f40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11f50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11f60 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11f70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11f80 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
11f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fa0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11fb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11fc0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
11fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11fe0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11ff0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12000 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12010 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12020 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12030 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12040 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12050 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12060 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
12070 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12080 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12090 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
120a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
120b0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
120c0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
120d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
120e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
120f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12100 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12110 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12120 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12140 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12150 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12160 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12170 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12180 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
12190 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
121a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
121b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
121d0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
121e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
121f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12200 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12210 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12220 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12230 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12240 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
12250 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12260 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12270 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12280 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12290 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
122a0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
122b0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
122c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
122d0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
122e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12300 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12310 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12320 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12330 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12340 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12350 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12360 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12370 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12380 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12390 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123a0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
123b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
123c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
123d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
123e0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
123f0 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
12400 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
12410 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
12420 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
12430 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
12440 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
12450 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
12460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12470 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12480 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66  abled, the .** f
12490 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
124a0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
124b0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
124c0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
124d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
124e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
124f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12500 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12510 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12520 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12530 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12540 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12550 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
12560 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
12570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12580 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
12590 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
125a0 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
125b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
125c0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
125d0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
125e0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
125f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
12600 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12610 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
12620 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
12630 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12640 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
12650 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12660 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
12670 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12680 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12690 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
126a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
126b0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
126c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
126d0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
126e0 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
126f0 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
12700 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
12710 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
12720 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
12730 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
12740 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
12750 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
12760 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
12770 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
12780 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
12790 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
127a0 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
127b0 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
127c0 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
127d0 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
127e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
127f0 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
12800 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
12810 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
12820 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
12830 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12840 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12850 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
12860 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
12870 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12880 68 72 65 61 64 20 61 6e 64 20 6e 6f 74 0a 2a 2a  hread and not.**
12890 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
128a0 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65  cratch buffer pe
128b0 72 20 74 68 72 65 61 64 20 77 68 65 6e 20 6e 6f  r thread when no
128c0 74 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  t performing.** 
128d0 61 20 5b 63 68 65 63 6b 70 6f 69 6e 74 5d 20 69  a [checkpoint] i
128e0 6e 20 5b 57 41 4c 20 6d 6f 64 65 5d 2e 0a 2a 2a  n [WAL mode]..**
128f0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
12900 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
12910 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
12920 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
12930 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
12940 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
12950 2c 20 65 78 63 65 70 74 20 77 68 65 6e 20 70 65  , except when pe
12960 72 66 6f 72 6d 69 6e 67 20 61 20 5b 63 68 65 63  rforming a [chec
12970 6b 70 6f 69 6e 74 5d 0a 2a 2a 20 69 6e 20 5b 57  kpoint].** in [W
12980 41 4c 20 6d 6f 64 65 5d 20 77 68 65 6e 20 74 68  AL mode] when th
12990 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
129a0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 69 73   request size is
129b0 20 61 20 73 6d 61 6c 6c 20 66 72 61 63 74 69 6f   a small fractio
129c0 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 73 69 7a 65  n.** of the size
129d0 20 6f 66 20 74 68 65 20 57 41 4c 20 66 69 6c 65   of the WAL file
129e0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
129f0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
12a00 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
12a10 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
12a20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12a30 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
12a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
12a50 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12a60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12a70 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12a80 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12a90 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12aa0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ab0 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
12ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12ad0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
12ae0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12af0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12b00 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12b10 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12b20 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12b30 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12b40 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12b50 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12b60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12b70 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12b80 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12b90 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12ba0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12bb0 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
12bc0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12bd0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
12be0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
12bf0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
12c00 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
12c10 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12c20 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12c30 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12c40 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12c50 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12c60 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12c70 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12c80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12c90 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12ca0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12cb0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
12cc0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
12cd0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
12ce0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
12cf0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
12d00 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
12d10 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12d20 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12d30 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12d40 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12d50 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12d60 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12d70 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12d80 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12d90 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12da0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12db0 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
12dc0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
12dd0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
12de0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
12df0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
12e00 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
12e10 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12e20 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12e30 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12e40 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12e50 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12e60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12e70 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12e80 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12e90 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12ea0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12eb0 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
12ec0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
12ed0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
12ee0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
12ef0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12f00 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
12f10 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12f20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12f30 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12f40 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12f50 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12f60 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12f70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12f80 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12f90 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12fa0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12fb0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
12fc0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
12fd0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
12fe0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12ff0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13000 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13010 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13020 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13030 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13040 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13050 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
13060 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
13070 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
13080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13090 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
130a0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
130b0 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
130c0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
130d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
130e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
130f0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
13100 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
13110 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13120 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13130 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13140 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
13150 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13160 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13170 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13180 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13190 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
131a0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
131b0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
131c0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
131d0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
131e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
131f0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
13200 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
13210 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
13220 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
13230 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
13240 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
13250 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
13260 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
13270 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13280 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
13290 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
132a0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
132b0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
132c0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
132d0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
132e0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
132f0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
13300 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
13310 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
13320 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13330 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
13340 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13350 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13360 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13370 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13380 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13390 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
133a0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
133b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
133c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
133d0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
133e0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
133f0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13400 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13410 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13420 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13430 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13440 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13450 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13460 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13470 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13480 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13490 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
134a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
134b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
134c0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
134d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
134e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
134f0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
13500 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
13510 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
13520 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
13530 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
13540 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
13550 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
13560 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
13570 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
13580 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
13590 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
135a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
135b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
135c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
135d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
135e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
135f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
13600 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13610 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13620 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13630 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13640 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
13650 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
13660 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
13670 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
13680 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
13690 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
136a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
136b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
136c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
136d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
136e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
136f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
13700 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
13710 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13720 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13730 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
13740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13750 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13760 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13770 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13780 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13790 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
137a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
137b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
137c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
137d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
137e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
137f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
13800 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
13810 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13820 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13830 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13840 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13850 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13860 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13870 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
13880 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13890 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
138a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
138b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
138c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
138d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
138e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
138f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
13900 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
13910 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13920 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13930 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13940 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13950 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13960 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13970 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13980 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13990 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
139a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
139b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
139d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
139e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
139f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13a00 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13a10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13a20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13a30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13a40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13a50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13a60 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13a70 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13a80 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13a90 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13aa0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13ab0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
13ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13ad0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
13ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13af0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
13b00 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
13b10 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13b20 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13b30 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13b40 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13b50 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13b60 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13b80 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13b90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13ba0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13bb0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
13bc0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
13bd0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
13be0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
13bf0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
13c00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
13c10 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13c20 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13c30 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13c40 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13c50 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13c60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13c70 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13c80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13c90 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13ca0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13cb0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13cc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
13cd0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
13ce0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13cf0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13d00 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13d10 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13d20 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13d30 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13d40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13d50 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13d60 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13d70 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13d80 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13d90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13da0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13db0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13dc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
13dd0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13de0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
13df0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13e00 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13e10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13e20 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13e30 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13e40 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13e50 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13e60 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13e70 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13e80 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13e90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13ea0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13eb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
13ed0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13ee0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
13ef0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
13f00 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
13f10 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13f20 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13f30 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13f40 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13f50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13f60 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13f70 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13f80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13f90 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13fa0 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13fb0 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
13fc0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
13fd0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
13fe0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
13ff0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
14000 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
14010 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
14020 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
14030 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
14040 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
14050 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
14060 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
14070 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
14080 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14090 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
140a0 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
140b0 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
140c0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
140d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
140f0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
14100 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
14110 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14130 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
14140 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
14150 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
14160 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
14170 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
14180 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
14190 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
141a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
141b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
141c0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
141d0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
141e0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
141f0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
14200 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
14210 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
14220 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
14230 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
14240 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
14250 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
14260 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
14270 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
14280 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
14290 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
142a0 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
142b0 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
142c0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
142d0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
142e0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
142f0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
14300 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
14310 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
14320 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
14330 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
14340 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
14350 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14360 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14370 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
14380 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
14390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
143a0 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
143b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
143c0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
143d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
143e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
143f0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
14400 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
14410 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
14420 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
14430 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
14440 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
14450 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
14460 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
14470 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
14480 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14490 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
144a0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
144b0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
144c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
144d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
144e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
144f0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
14500 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
14510 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
14520 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
14530 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
14540 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
14550 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
14560 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
14570 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
14580 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
14590 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
145a0 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
145b0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
145c0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
145d0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
145e0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
145f0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
14600 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
14610 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
14620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14630 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
14640 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
14650 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14660 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
14670 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
14680 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
14690 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
146a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
146b0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
146c0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
146d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
146e0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
146f0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
14700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
14710 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14720 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14730 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14740 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
14750 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
14760 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
14770 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14780 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14790 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
147a0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
147b0 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
147c0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
147d0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
147e0 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
147f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14800 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14810 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14820 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14830 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14840 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14850 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14860 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14870 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14880 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14890 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
148a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
148b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
148c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
148d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
148e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
148f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
14900 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
14910 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14920 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14930 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14940 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14950 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14960 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14970 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14980 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14990 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
149a0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
149b0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
149c0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
149d0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
149e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
149f0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
14a00 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14a10 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14a20 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14a30 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14a40 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14a50 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14a60 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14a70 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14a80 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14a90 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14aa0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14ab0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14ac0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
14ad0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
14ae0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14af0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
14b00 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14b10 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14b20 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14b30 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14b40 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14b50 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14b60 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14b70 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14b80 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14b90 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14ba0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14bb0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
14bc0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
14bd0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
14be0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
14bf0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
14c00 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
14c10 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14c20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14c30 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14c40 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14c50 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14c60 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14c70 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14c80 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14c90 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14ca0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14cb0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
14cc0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
14cd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
14ce0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
14cf0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14d00 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
14d10 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14d20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14d30 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14d40 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14d50 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14d60 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14d70 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14d80 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14d90 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14da0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14db0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
14dc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
14dd0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
14de0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
14df0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
14e00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
14e10 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14e20 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14e30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14e40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14e50 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14e60 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14e70 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14e80 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14e90 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14ea0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14eb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14ec0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
14ed0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
14ee0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
14ef0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
14f00 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
14f10 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14f20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f30 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14f40 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14f50 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14f60 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14f80 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14f90 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14fa0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
14fb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
14fc0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
14fd0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
14fe0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
14ff0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15000 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
15010 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15020 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15030 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15040 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
15050 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
15060 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15070 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
15080 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
15090 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
150a0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
150b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
150c0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
150d0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
150e0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
150f0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15100 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
15110 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
15120 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
15130 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15140 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
15150 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
15160 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15170 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15180 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15190 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
151a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
151b0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
151c0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
151d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
151e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
151f0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
15200 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15210 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15220 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15230 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15240 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15250 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15260 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15270 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
15280 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
15290 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
152a0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
152b0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
152c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
152d0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
152e0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
152f0 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
15300 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15310 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
15320 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
15330 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
15340 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
15350 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
15360 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
15370 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
15380 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15390 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
153a0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
153b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
153c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
153d0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
153e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
153f0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
15400 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
15410 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
15420 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
15430 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
15440 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
15450 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
15460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15470 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
15480 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
15490 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
154a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
154b0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
154c0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
154d0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
154e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
154f0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
15500 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
15510 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
15520 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15530 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
15540 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
15550 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
15560 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15580 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
15590 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
155a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
155b0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
155c0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
155d0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
155e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155f0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
15600 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
15610 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
15620 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
15630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
15640 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
15650 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
15660 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
15670 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15680 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
15690 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
156a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
156b0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
156c0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
156d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
156e0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
156f0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
15700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15710 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15720 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15730 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15740 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15750 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15760 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15770 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15780 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
157a0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
157b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
157c0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
157d0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
157e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
157f0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15810 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15820 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15840 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
15850 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15860 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15870 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15880 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15890 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
158a0 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
158b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158c0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
158d0 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
158e0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
158f0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15900 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15910 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15920 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15930 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15940 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
15950 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15960 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15970 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15980 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
15990 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
159a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
159b0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
159c0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
159d0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
159e0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
159f0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15a00 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15a10 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15a20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15a30 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15a40 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15a50 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15a60 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15a70 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15a80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15a90 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15aa0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15ab0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15ac0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ad0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15ae0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15af0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15b00 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15b10 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15b20 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15b30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15b40 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15b50 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15b60 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15b70 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15b80 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15b90 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15ba0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15bb0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15bc0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15bd0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15be0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15bf0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15c00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15c10 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15c20 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15c30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15c40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15c50 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15c60 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15c70 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15c80 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15c90 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15cb0 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15cc0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15cd0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15ce0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15cf0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15d00 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15d10 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15d20 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15d30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d40 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15d50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15d60 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15d70 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15d80 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15d90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15da0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15db0 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15dc0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15dd0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15de0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15df0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15e00 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15e10 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15e20 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15e30 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15e40 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15e50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15e60 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15e70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15e80 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15e90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15ea0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15eb0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15ec0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15ed0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15ee0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15ef0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15f00 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15f10 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15f20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15f30 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15f40 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15f50 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15f60 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15f70 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15f80 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15f90 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15fa0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15fb0 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
15fc0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
15fd0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
15fe0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
15ff0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16000 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
16010 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
16020 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
16030 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
16040 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
16050 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
16060 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
16070 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
16080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
16090 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
160a0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
160b0 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
160c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
160d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
160e0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
160f0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
16100 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
16110 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
16120 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
16130 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
16140 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
16150 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
16160 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
16170 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
16180 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
16190 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
161a0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
161b0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
161c0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
161d0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
161e0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
161f0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
16200 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
16210 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
16220 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
16230 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16240 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
16250 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
16260 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
16270 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
16280 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
16290 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
162a0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
162b0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
162c0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
162d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
162e0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
162f0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
16300 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
16310 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16320 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
16330 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
16340 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
16350 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16360 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
16370 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
16380 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
16390 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
163a0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
163b0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
163c0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
163d0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
163e0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
163f0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16400 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
16410 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
16420 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
16430 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
16440 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
16450 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
16460 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
16470 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16480 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16490 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
164a0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
164b0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
164c0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
164d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
164e0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
164f0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
16500 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
16510 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
16520 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
16530 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
16540 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
16550 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
16560 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
16570 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16580 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16590 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
165a0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
165b0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
165c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
165d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
165e0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
165f0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
16600 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16610 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
16620 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
16630 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
16640 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
16650 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
16660 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
16670 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
16680 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
16690 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
166a0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
166b0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
166c0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
166d0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
166e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
166f0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
16700 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
16710 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16720 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16730 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16740 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
16750 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16760 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
16770 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
16780 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
16790 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
167a0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
167b0 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
167c0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
167d0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
167e0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
167f0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
16800 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
16810 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
16820 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
16830 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
16840 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
16850 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
16860 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
16870 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
16880 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
16890 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
168a0 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
168b0 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
168c0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
168d0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
168e0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
168f0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
16900 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
16910 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
16920 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
16930 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
16940 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
16950 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
16960 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
16970 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16980 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
16990 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
169a0 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
169b0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
169c0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
169d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
169e0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
169f0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
16a00 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
16a10 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16a20 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
16a30 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
16a40 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16a50 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
16a60 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
16a70 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
16a80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16a90 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
16aa0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
16ab0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
16ac0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
16ad0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
16ae0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
16af0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
16b00 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
16b10 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
16b20 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
16b30 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
16b40 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
16b50 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
16b60 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
16b70 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16b80 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16b90 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
16ba0 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16bb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16bc0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16bd0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
16be0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
16bf0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
16c00 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
16c10 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
16c20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16c30 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
16c40 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
16c50 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
16c60 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
16c70 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16c80 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
16c90 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
16ca0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
16cb0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
16cc0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
16cd0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
16ce0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
16cf0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
16d00 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
16d10 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
16d20 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
16d30 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
16d40 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
16d50 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16d60 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
16d70 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
16d80 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
16d90 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
16da0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
16db0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
16dc0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
16dd0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
16de0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
16df0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
16e00 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
16e10 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
16e20 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
16e30 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
16e40 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16e50 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
16e60 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
16e70 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16e80 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
16e90 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
16ea0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
16eb0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
16ec0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
16ed0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
16ee0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
16ef0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
16f00 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
16f10 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
16f20 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
16f30 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
16f40 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
16f50 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16f60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
16f70 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
16f80 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
16f90 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
16fa0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
16fb0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16fc0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
16fd0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
16fe0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
16ff0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
17000 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
17010 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
17020 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
17030 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
17040 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
17050 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17060 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
17070 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17080 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
17090 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
170a0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
170b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
170c0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
170d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
170e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
170f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17100 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
17110 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
17120 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17130 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17140 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17150 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
17160 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
17170 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
17180 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
17190 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
171a0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
171b0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
171c0 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
171d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
171e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
171f0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
17200 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
17210 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
17220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
17230 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
17240 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
17250 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
17260 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
17270 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
17280 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
17290 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
172a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
172b0 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
172c0 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
172d0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
172e0 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
172f0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
17300 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17310 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
17320 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
17330 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
17340 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
17350 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
17360 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
17370 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
17380 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
17390 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
173a0 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
173b0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
173c0 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
173d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
173e0 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
173f0 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
17400 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
17410 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
17420 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
17430 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
17440 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
17450 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
17460 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
17470 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
17480 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
17490 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
174a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
174b0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
174c0 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
174d0 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
174e0 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
174f0 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
17500 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
17510 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
17520 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17530 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
17540 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
17550 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
17560 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
17570 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
17580 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
17590 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
175a0 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
175b0 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
175c0 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
175d0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
175e0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
175f0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
17600 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
17610 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
17620 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
17630 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
17640 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
17650 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
17660 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
17670 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
17680 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
17690 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
176a0 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
176b0 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
176c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
176d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
176e0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
176f0 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
17700 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
17710 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
17720 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
17730 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
17740 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
17750 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
17760 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
17770 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
17780 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
17790 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
177a0 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
177b0 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
177c0 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
177d0 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
177e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
177f0 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
17800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
17810 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
17820 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
17830 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
17840 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
17850 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
17860 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
17870 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
17880 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
17890 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
178a0 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
178b0 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
178c0 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
178d0 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
178e0 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
178f0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17900 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
17910 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17920 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
17930 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
17940 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
17950 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
17960 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17970 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
17980 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
17990 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
179a0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
179b0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
179c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
179d0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
179e0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
179f0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
17a00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
17a10 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17a20 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
17a30 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
17a40 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
17a50 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
17a60 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17a70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17a80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17a90 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
17aa0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17ab0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17ac0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
17ad0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
17ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17af0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
17b00 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17b20 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17b30 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
17b40 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
17b50 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
17b60 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
17b70 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
17b80 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
17b90 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
17ba0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
17bb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17bc0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
17bd0 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
17be0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
17bf0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
17c00 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
17c10 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
17c20 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
17c30 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
17c40 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
17c50 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
17c60 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17c70 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
17c80 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
17c90 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
17ca0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
17cb0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
17cc0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
17cd0 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
17ce0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
17cf0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
17d00 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
17d10 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
17d20 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
17d30 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
17d40 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
17d50 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
17d60 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
17d70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
17d80 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
17d90 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
17da0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
17db0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
17dc0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
17dd0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17de0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17df0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17e00 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17e10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17e20 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17e30 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17e40 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17e50 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17e60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
17e70 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
17e80 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
17e90 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
17ea0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17eb0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17ec0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
17ed0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
17ee0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
17ef0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17f00 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
17f10 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
17f20 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
17f30 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
17f40 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
17f50 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
17f60 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
17f70 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
17f80 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
17f90 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
17fa0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
17fb0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
17fc0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
17fd0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
17fe0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
17ff0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
18000 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
18010 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
18020 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
18030 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
18040 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
18050 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
18060 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18070 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
18080 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
18090 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
180a0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
180b0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
180c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
180d0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
180e0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
180f0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
18100 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
18110 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
18120 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
18130 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
18140 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
18150 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
18160 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18170 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
18180 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
18190 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
181a0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
181b0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
181c0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
181d0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
181e0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
181f0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
18200 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
18210 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
18220 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
18230 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
18240 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
18250 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
18260 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
18270 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
18280 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
18290 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
182a0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
182b0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
182c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
182d0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
182e0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
182f0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
18300 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
18310 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
18320 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18330 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
18340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18350 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
18360 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
18370 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
18380 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
18390 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
183a0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
183b0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
183c0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
183d0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
183e0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
183f0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
18400 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
18410 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
18420 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18430 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
18440 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
18450 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
18460 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
18470 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
18480 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
18490 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
184a0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
184b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
184c0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
184d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
184e0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
184f0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
18500 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
18510 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
18520 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
18530 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
18540 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18550 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18560 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
18570 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
18580 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
18590 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
185a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
185b0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
185c0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
185d0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
185e0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
185f0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
18600 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
18610 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
18620 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18630 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
18640 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
18650 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
18660 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18670 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
18680 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
18690 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
186a0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
186b0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
186c0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
186d0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
186e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
186f0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
18700 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
18710 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
18720 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
18730 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
18740 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
18750 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
18760 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
18770 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
18780 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
18790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
187a0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
187b0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
187c0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
187d0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
187e0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
187f0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
18800 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
18810 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
18820 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
18830 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
18840 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
18850 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
18860 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
18870 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
18880 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
18890 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
188a0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
188b0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
188c0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
188d0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
188e0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
188f0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
18900 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
18910 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
18920 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
18930 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
18940 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
18950 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
18960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
18970 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
18980 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
18990 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
189a0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
189b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
189c0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
189d0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
189e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
189f0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
18a00 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
18a10 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
18a20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
18a30 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
18a40 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
18a50 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
18a60 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
18a70 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
18a80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18a90 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
18aa0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
18ab0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
18ac0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
18ad0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
18ae0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
18af0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
18b00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
18b10 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
18b20 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
18b30 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
18b40 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
18b50 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18b60 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
18b70 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
18b80 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
18b90 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
18ba0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
18bb0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
18bc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
18bd0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
18be0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18bf0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
18c00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
18c10 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
18c20 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
18c30 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
18c40 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
18c50 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
18c60 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
18c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18c80 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
18c90 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
18ca0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
18cb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
18cc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18cd0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
18ce0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
18cf0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
18d00 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
18d10 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
18d20 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
18d30 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
18d40 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
18d50 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
18d60 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
18d70 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
18d80 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
18d90 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
18da0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
18db0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
18dc0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18dd0 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
18de0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
18df0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
18e00 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
18e10 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
18e20 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
18e30 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
18e40 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
18e50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
18e60 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
18e70 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
18e80 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
18e90 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
18ea0 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
18eb0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
18ec0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
18ed0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
18ee0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
18ef0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
18f00 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
18f10 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
18f20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
18f30 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18f40 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
18f50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
18f60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
18f70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18f80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
18f90 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
18fa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
18fb0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
18fc0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
18fd0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
18fe0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18ff0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
19000 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
19010 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19020 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
19030 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
19040 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19050 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
19060 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
19070 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
19080 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
19090 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
190a0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
190b0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
190c0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
190d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
190e0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
190f0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
19100 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
19110 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19120 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
19130 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
19140 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
19150 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
19160 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
19170 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
19180 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
19190 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
191a0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
191b0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
191c0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
191d0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
191e0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
191f0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
19200 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
19210 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
19220 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
19230 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
19240 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
19250 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
19260 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
19270 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19280 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
19290 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
192a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
192b0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
192c0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
192d0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
192e0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
192f0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
19300 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
19310 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
19320 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
19330 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19340 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19350 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19360 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19370 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19380 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19390 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
193a0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
193b0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
193c0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
193d0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
193e0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
193f0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
19400 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19410 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
19420 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
19430 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
19440 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19450 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19460 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19470 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19480 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19490 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
194a0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
194b0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
194c0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
194d0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
194e0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
194f0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
19500 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
19510 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
19520 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
19530 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
19540 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19550 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19560 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19570 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19580 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
19590 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
195a0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
195b0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
195c0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
195d0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
195e0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
195f0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
19600 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19610 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
19620 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
19630 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
19640 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
19650 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
19660 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
19670 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
19680 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
19690 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
196a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
196b0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
196c0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
196d0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
196e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
196f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19700 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
19710 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
19720 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
19730 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
19740 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
19750 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
19760 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
19770 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
19780 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
19790 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
197a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
197b0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
197c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
197d0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
197e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
197f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19800 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
19810 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
19820 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
19830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19840 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
19850 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
19860 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
19870 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
19880 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
19890 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
198a0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
198b0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
198c0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
198d0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
198e0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
198f0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
19900 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
19910 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
19920 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
19930 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
19940 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
19950 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
19960 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
19970 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
19980 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
19990 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
199a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
199b0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
199c0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
199d0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
199e0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
199f0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
19a00 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
19a10 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
19a20 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
19a30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
19a40 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19a50 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19a60 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
19a70 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
19a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
19a90 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
19aa0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
19ab0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
19ac0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
19ad0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
19ae0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
19af0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
19b00 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
19b10 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
19b20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
19b30 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
19b40 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
19b50 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
19b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19b70 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
19b80 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
19b90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
19ba0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
19bb0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
19bc0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
19bd0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
19be0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
19bf0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
19c00 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19c10 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
19c20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
19c30 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
19c40 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
19c50 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
19c60 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
19c70 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
19c80 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
19c90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
19ca0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
19cb0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
19cc0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
19cd0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
19ce0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
19cf0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
19d00 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
19d10 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
19d20 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
19d30 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
19d40 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
19d50 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
19d60 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
19d70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
19d80 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
19d90 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
19da0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
19db0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
19dc0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
19dd0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
19de0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
19df0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19e00 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
19e10 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
19e20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19e30 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
19e40 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
19e50 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
19e60 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
19e70 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
19e80 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
19e90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
19ea0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
19eb0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
19ec0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
19ed0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
19ee0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
19ef0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
19f00 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
19f10 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
19f20 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
19f30 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
19f40 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
19f50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19f60 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
19f70 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
19f80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
19f90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
19fa0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
19fb0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
19fc0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
19fd0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
19fe0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
19ff0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1a000 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a010 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1a020 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1a030 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a040 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1a050 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1a060 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a070 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1a080 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1a090 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1a0a0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1a0b0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1a0c0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a0d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a0e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a0f0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1a100 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1a110 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a120 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1a130 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1a140 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1a150 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1a160 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1a170 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1a180 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a190 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1a1a0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1a1b0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1a1c0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1a1d0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1a1e0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1a1f0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1a200 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1a210 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1a220 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1a230 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1a240 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1a250 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1a260 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a270 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a280 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1a290 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a2a0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1a2b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a2c0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1a2d0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1a2e0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a2f0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1a300 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a310 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1a320 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a330 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1a340 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a350 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1a360 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1a370 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1a380 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1a390 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1a3a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a3b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1a3c0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1a3d0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1a3e0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1a3f0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1a400 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1a410 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a420 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1a430 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1a440 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1a450 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1a460 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1a470 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1a480 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1a490 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1a4a0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1a4b0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1a4c0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1a4d0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1a4e0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1a4f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1a500 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1a510 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1a520 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1a530 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1a540 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1a550 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1a560 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1a570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a580 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1a590 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a5a0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1a5b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1a5c0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1a5d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a5e0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1a5f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1a600 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1a610 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1a620 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1a630 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1a640 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a650 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1a660 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1a670 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1a680 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1a690 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1a6a0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a6b0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1a6c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1a6d0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1a6e0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1a6f0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1a700 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1a710 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1a720 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1a730 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1a740 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1a750 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1a760 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1a770 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1a780 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1a790 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1a7a0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1a7b0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1a7c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1a7d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1a7e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1a7f0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1a800 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1a810 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1a820 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1a830 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1a840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a850 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1a860 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1a870 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1a880 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1a890 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1a8a0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1a8b0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1a8c0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a8d0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1a8e0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1a8f0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1a900 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1a910 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1a920 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1a930 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1a940 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1a950 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1a960 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1a970 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1a980 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1a990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a9a0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1a9b0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1a9c0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1a9d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1a9e0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1a9f0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1aa00 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1aa10 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1aa20 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1aa30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aa40 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1aa50 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1aa60 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1aa70 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1aa80 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1aa90 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1aaa0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1aab0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1aac0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1aad0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1aae0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1aaf0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1ab00 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1ab10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ab20 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1ab30 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1ab40 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1ab50 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1ab60 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1ab70 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1ab80 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1ab90 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1aba0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1abb0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1abc0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1abd0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1abe0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1abf0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1ac00 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1ac10 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1ac20 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ac30 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1ac40 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1ac50 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1ac60 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1ac70 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1ac80 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1ac90 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1aca0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1acb0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1acc0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1acd0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1ace0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1acf0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1ad00 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1ad10 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1ad20 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1ad30 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1ad40 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1ad50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1ad60 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1ad70 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1ad80 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1ad90 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1ada0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1adb0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1adc0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1add0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1ade0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1adf0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1ae00 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1ae10 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1ae20 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1ae30 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1ae40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1ae50 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1ae60 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1ae70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1ae80 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1ae90 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1aea0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1aeb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1aec0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1aed0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1aee0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1aef0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1af00 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1af10 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1af20 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1af30 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1af40 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1af50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1af60 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1af70 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1af80 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1af90 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1afa0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1afb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1afc0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1afd0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1afe0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1aff0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b000 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1b010 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1b020 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1b030 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1b040 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1b050 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1b060 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1b070 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b080 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1b090 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1b0a0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1b0b0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1b0c0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1b0d0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1b0e0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1b0f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1b100 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b110 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1b120 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1b130 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1b140 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1b150 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1b160 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1b170 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1b180 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1b190 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1b1a0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1b1b0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1b1c0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1b1d0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1b1e0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1b1f0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1b200 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1b210 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1b220 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1b230 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1b240 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1b250 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1b260 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1b270 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b280 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b290 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b2a0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1b2b0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1b2c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b2d0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1b2e0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1b2f0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1b300 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1b310 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b320 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1b330 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1b340 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1b350 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1b360 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1b370 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1b380 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1b390 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1b3a0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1b3b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b3c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1b3d0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1b3e0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1b3f0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1b400 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1b410 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1b420 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1b430 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1b440 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b450 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b460 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b470 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1b480 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1b490 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b4a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1b4b0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1b4c0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1b4d0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1b4e0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1b4f0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1b500 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1b510 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b520 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b530 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b540 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1b550 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1b560 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b570 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1b580 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1b590 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1b5a0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1b5b0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1b5c0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1b5d0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1b5e0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1b5f0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1b600 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1b610 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1b620 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1b630 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1b640 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1b650 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1b660 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1b670 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1b680 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1b690 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1b6a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1b6b0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1b6c0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1b6d0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1b6e0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1b6f0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1b700 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1b710 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1b720 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1b730 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1b740 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1b750 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1b760 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1b770 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1b780 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1b790 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1b7a0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1b7b0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1b7c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b7d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b7e0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1b7f0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1b800 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1b810 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1b820 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1b830 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1b840 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1b850 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1b860 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1b870 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1b880 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1b890 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1b8a0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1b8b0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1b8c0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1b8d0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1b8e0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1b8f0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1b900 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1b910 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1b920 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1b930 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1b940 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1b950 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1b960 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1b970 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1b980 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b990 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1b9a0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1b9b0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1b9c0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b9d0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1b9e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1b9f0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1ba00 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1ba10 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1ba20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1ba30 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1ba40 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1ba50 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1ba60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1ba70 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1ba80 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1ba90 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1baa0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1bab0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1bac0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1bad0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1bae0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1baf0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1bb00 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1bb10 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1bb20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bb30 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1bb40 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1bb50 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1bb60 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1bb70 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1bb80 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1bb90 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1bba0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1bbb0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1bbc0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1bbd0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1bbe0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1bbf0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1bc00 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1bc10 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1bc20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bc30 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1bc40 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1bc50 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1bc60 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1bc70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1bc80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1bc90 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1bca0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1bcb0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1bcc0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1bcd0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1bce0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1bcf0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1bd00 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1bd10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1bd20 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1bd30 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1bd40 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1bd50 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1bd60 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1bd70 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1bd80 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1bd90 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1bda0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1bdb0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1bdc0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1bdd0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1bde0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1bdf0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1be00 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1be10 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1be20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1be30 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1be40 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1be50 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1be60 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1be70 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1be80 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1be90 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1bea0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1beb0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1bec0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1bed0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1bee0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1bef0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1bf00 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1bf10 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1bf20 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1bf30 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1bf40 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1bf50 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1bf60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1bf70 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1bf80 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1bf90 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1bfa0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1bfb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bfc0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1bfd0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1bfe0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1bff0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1c000 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1c010 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c020 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1c030 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c040 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1c050 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1c060 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1c070 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1c080 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1c090 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c0a0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1c0b0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1c0c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c0d0 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1c0e0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1c0f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1c100 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1c110 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1c120 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1c130 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1c140 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1c150 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1c160 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c170 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1c180 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1c190 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1c1a0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1c1b0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1c1c0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1c1d0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1c1e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1c1f0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1c200 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1c210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1c220 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1c230 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1c240 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1c250 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1c260 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1c270 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c280 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1c290 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1c2a0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1c2b0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1c2c0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1c2d0 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1c2e0 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1c2f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c300 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1c310 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1c320 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1c330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1c340 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1c350 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1c360 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1c370 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1c380 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1c390 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1c3a0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1c3b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1c3c0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1c3d0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1c3e0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1c3f0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1c400 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c410 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1c420 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1c430 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1c440 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1c450 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1c460 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1c470 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1c480 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c490 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1c4a0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1c4b0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1c4c0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1c4d0 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1c4e0 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1c4f0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1c500 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1c510 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1c520 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1c530 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1c540 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1c550 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1c560 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1c570 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1c580 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1c590 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1c5a0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1c5b0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1c5c0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1c5d0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1c5e0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1c5f0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1c600 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1c610 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1c620 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1c630 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1c640 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1c650 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1c660 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1c670 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1c680 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1c690 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1c6a0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1c6b0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1c6c0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1c6d0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1c6e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1c6f0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1c700 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1c710 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1c720 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1c730 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1c740 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1c750 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1c760 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1c770 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1c780 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1c790 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1c7a0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1c7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1c7c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1c7d0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1c7e0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1c7f0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1c800 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1c810 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1c820 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1c830 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1c840 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1c850 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1c860 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1c870 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1c880 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1c890 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1c8a0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1c8b0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1c8c0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1c8d0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1c8e0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1c8f0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1c900 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1c910 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1c920 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1c930 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1c940 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1c950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1c960 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1c970 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1c980 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1c990 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1c9a0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1c9b0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1c9c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1c9d0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1c9e0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1c9f0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1ca00 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1ca10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1ca20 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1ca30 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1ca40 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1ca50 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1ca60 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1ca70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ca80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1ca90 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1caa0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1cab0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1cac0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1cad0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1cae0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1caf0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1cb00 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1cb10 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1cb20 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1cb30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1cb40 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1cb50 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1cb60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1cb70 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1cb80 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1cb90 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1cba0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1cbb0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1cbc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1cbd0 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1cbe0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1cbf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1cc00 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1cc10 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1cc20 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1cc30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cc40 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1cc50 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1cc60 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1cc70 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1cc80 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1cc90 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1cca0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1ccb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ccc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ccd0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1cce0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1ccf0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1cd00 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1cd10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cd20 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1cd30 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1cd40 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1cd50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1cd60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1cd70 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1cd80 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1cd90 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1cda0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1cdb0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1cdc0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1cdd0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1cde0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1cdf0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1ce00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1ce10 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1ce20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1ce30 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1ce40 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1ce50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1ce60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ce70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1ce80 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ce90 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1cea0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1ceb0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1cec0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1ced0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1cee0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1cef0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1cf00 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1cf10 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1cf20 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1cf30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1cf40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1cf50 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1cf60 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1cf70 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1cf80 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1cf90 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1cfa0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cfb0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1cfc0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1cfd0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1cfe0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1cff0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1d000 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1d010 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1d020 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d030 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1d040 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1d050 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1d060 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1d070 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1d080 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1d090 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1d0a0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1d0b0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1d0c0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1d0d0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1d0e0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1d0f0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1d100 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1d110 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1d120 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1d130 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1d140 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1d150 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1d160 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1d170 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1d180 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1d190 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1d1a0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1d1b0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1d1c0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1d1d0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1d1e0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1d1f0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1d200 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1d210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1d220 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1d230 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1d240 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1d250 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1d260 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1d270 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1d280 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1d290 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1d2a0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1d2b0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1d2c0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1d2d0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1d2e0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1d2f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1d300 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1d310 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1d320 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1d330 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1d340 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1d350 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1d360 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1d370 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1d380 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1d390 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1d3a0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1d3b0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1d3c0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1d3d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1d3e0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1d3f0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1d400 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1d410 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1d420 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1d430 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1d440 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1d450 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1d460 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1d470 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1d480 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1d490 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1d4a0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1d4b0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1d4c0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1d4d0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1d4e0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1d4f0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1d500 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1d510 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1d520 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1d530 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1d540 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1d550 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d560 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1d570 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1d580 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1d590 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d5a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1d5b0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1d5c0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1d5d0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1d5e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1d5f0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1d600 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d610 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1d620 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1d630 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1d640 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1d650 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1d660 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1d670 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1d680 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1d690 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1d6a0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1d6b0 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1d6c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d6d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d6e0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1d6f0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1d700 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1d710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d720 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1d730 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1d740 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1d750 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1d760 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1d770 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1d780 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1d790 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1d7a0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1d7b0 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1d7c0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1d7d0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1d7e0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1d7f0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1d800 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1d810 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1d820 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d830 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1d840 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1d850 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1d860 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1d870 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1d880 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1d890 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d8a0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1d8b0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1d8c0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1d8d0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1d8e0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1d8f0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1d900 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1d910 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d920 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1d930 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1d940 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1d950 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1d960 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d970 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1d980 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1d990 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d9a0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1d9b0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1d9c0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1d9d0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1d9e0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1d9f0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1da00 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1da10 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1da20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1da30 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1da40 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1da50 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1da60 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1da70 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1da80 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1da90 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1daa0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1dab0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1dac0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1dad0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1dae0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1daf0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1db00 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1db10 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1db20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1db30 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1db40 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1db50 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1db60 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1db70 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1db80 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1db90 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1dba0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1dbb0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1dbc0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1dbd0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1dbe0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1dbf0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1dc00 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1dc10 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1dc20 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1dc30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1dc40 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1dc50 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1dc60 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1dc70 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1dc80 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1dc90 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1dca0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1dcb0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1dcc0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1dcd0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1dce0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1dcf0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1dd00 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1dd10 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1dd20 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1dd30 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1dd40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1dd50 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1dd60 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1dd70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1dd80 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1dd90 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1dda0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1ddb0 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1ddc0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1ddd0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1dde0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1ddf0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1de00 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1de10 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1de20 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1de30 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1de40 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1de50 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1de60 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1de70 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1de80 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1de90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1dea0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1deb0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1dec0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1ded0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1dee0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1def0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1df00 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1df10 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1df20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1df30 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1df40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1df50 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1df60 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1df70 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1df80 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1df90 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1dfa0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1dfb0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1dfc0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1dfd0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1dfe0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1dff0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1e000 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1e010 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1e020 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1e030 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1e040 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1e050 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1e060 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1e070 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1e080 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1e090 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1e0a0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1e0b0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1e0c0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1e0d0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1e0e0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1e0f0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1e100 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1e110 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1e120 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e130 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1e140 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1e150 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1e160 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1e170 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1e180 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1e190 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1e1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1e1b0 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1e1c0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1e1d0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1e1e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1e1f0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1e200 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1e210 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1e220 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1e230 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1e240 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1e250 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1e260 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1e270 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1e280 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1e290 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1e2a0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1e2b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e2c0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1e2d0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1e2e0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1e2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e300 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1e310 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e320 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1e330 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1e340 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1e350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e360 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1e370 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1e380 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1e390 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1e3a0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1e3b0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1e3c0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1e3d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1e3e0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1e3f0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1e400 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1e410 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1e420 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1e430 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1e440 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1e450 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1e460 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1e470 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1e480 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1e490 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e4a0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1e4b0 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1e4c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e4d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1e4e0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1e4f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e500 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1e510 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1e520 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1e530 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1e540 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1e550 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1e560 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1e570 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1e580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1e590 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1e5a0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1e5b0 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1e5c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1e5d0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1e5e0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1e5f0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1e600 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1e610 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1e620 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1e630 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1e640 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1e650 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1e660 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1e670 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1e680 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e690 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1e6a0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1e6b0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1e6c0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1e6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1e6e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1e6f0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1e700 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1e710 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1e720 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1e730 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1e740 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1e750 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1e760 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1e770 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1e780 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1e790 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1e7a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1e7b0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1e7c0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1e7d0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1e7e0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1e7f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1e800 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1e810 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1e820 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1e830 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1e840 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1e850 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1e860 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1e870 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1e880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e890 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1e8a0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1e8b0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1e8c0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1e8d0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1e8e0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1e8f0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1e900 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1e910 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1e920 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1e930 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1e940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1e950 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1e960 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1e970 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1e980 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1e990 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1e9a0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1e9b0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1e9c0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1e9d0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1e9e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1e9f0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1ea00 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1ea10 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1ea20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1ea30 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1ea40 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1ea50 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1ea60 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1ea70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ea80 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1ea90 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1eaa0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1eab0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1eac0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1ead0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1eae0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1eaf0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1eb00 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1eb10 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1eb20 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1eb30 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1eb40 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1eb50 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1eb60 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1eb70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1eb80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1eb90 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1eba0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1ebb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1ebc0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ebd0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1ebe0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1ebf0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1ec00 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1ec10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ec20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ec30 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1ec40 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1ec50 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1ec60 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1ec70 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1ec80 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1ec90 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1eca0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1ecb0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1ecc0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1ecd0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1ece0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ecf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1ed10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1ed20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1ed30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ed40 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1ed50 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1ed60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ed70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ed80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ed90 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1eda0 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1edb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1edc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1edd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ede0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1edf0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1ee00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ee10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ee20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee30 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1ee40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ee50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ee60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ee70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ee80 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1ee90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1eea0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1eeb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eec0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1eed0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1eee0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1eef0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ef00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ef10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1ef20 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1ef30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1ef40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ef50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ef60 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1ef70 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1ef80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1ef90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1efa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1efb0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1efc0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1efd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1efe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1eff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f000 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1f010 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1f020 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f030 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f050 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1f060 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1f070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f080 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f0a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1f0b0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1f0c0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1f0d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f0e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f0f0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1f100 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1f110 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f120 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f140 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1f150 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1f160 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1f170 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f190 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1f1a0 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1f1b0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f1c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f1d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f1e0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1f1f0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1f200 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1f210 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1f220 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f230 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1f240 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1f250 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1f260 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f270 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1f280 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1f290 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1f2a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f2b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f2c0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1f2d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1f2e0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1f2f0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1f300 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1f310 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1f320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1f330 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1f340 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1f350 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1f360 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1f380 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1f390 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f3a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f3b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1f3c0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1f3d0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1f3e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f3f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f400 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1f410 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1f420 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f430 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1f440 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f450 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1f460 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1f470 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1f480 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f490 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f4a0 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1f4b0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1f4c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f4d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f4e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f4f0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1f500 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1f510 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1f520 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f530 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f540 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1f550 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1f560 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1f570 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f590 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1f5a0 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1f5b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f5c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f5d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f5e0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1f5f0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1f600 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f610 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f630 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1f640 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1f650 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1f660 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1f670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1f680 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1f690 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1f6a0 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1f6b0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1f6c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1f6d0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1f6e0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1f6f0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1f700 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1f710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1f720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f730 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1f740 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
1f750 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
1f760 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
1f770 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
1f780 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f790 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
1f7a0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1f7b0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1f7c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1f7d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1f7e0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
1f7f0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
1f800 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
1f810 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
1f820 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
1f830 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
1f840 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1f850 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1f860 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1f870 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
1f880 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
1f890 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
1f8a0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
1f8b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
1f8c0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
1f8d0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
1f8e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
1f8f0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
1f900 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
1f910 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
1f920 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
1f930 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
1f940 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
1f950 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
1f960 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
1f970 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
1f980 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
1f990 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
1f9a0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1f9b0 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1f9c0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1f9d0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1f9e0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1f9f0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1fa00 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1fa10 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
1fa20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
1fa30 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
1fa40 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
1fa50 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
1fa60 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
1fa70 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
1fa80 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
1fa90 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
1faa0 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
1fab0 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
1fac0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1fad0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1fae0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1faf0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1fb00 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1fb10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1fb20 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1fb30 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1fb40 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1fb50 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1fb60 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1fb70 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1fb80 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1fb90 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1fba0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1fbb0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1fbc0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1fbd0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1fbe0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1fbf0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1fc00 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1fc10 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1fc20 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1fc30 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1fc40 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1fc50 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1fc60 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1fc70 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1fc80 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1fc90 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1fca0 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1fcb0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1fcc0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1fcd0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1fce0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1fcf0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1fd00 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1fd10 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1fd20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1fd30 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1fd40 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1fd50 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1fd60 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1fd70 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1fd80 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1fd90 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1fda0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1fdb0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1fdc0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1fdd0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1fde0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1fdf0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1fe00 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1fe10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fe20 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1fe30 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1fe40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fe50 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1fe60 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1fe70 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1fe80 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1fe90 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1fea0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1feb0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1fec0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1fed0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1fee0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1fef0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1ff00 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1ff10 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1ff20 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1ff30 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1ff40 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1ff50 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1ff60 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1ff70 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1ff80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1ff90 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1ffa0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1ffb0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1ffc0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1ffd0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1ffe0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1fff0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
20000 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
20010 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
20020 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
20030 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
20040 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
20050 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
20060 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
20070 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
20080 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
20090 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
200a0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
200b0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
200c0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
200d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
200e0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
200f0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
20100 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
20110 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
20120 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
20130 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
20140 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
20150 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
20160 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
20170 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
20180 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
20190 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
201a0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
201b0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
201c0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
201d0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
201e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
201f0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
20200 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
20210 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
20220 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
20230 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
20240 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
20250 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
20260 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
20270 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
20280 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
20290 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
202a0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
202b0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
202c0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
202d0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
202e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
202f0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
20300 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20310 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
20320 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20330 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20340 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
20350 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20360 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20370 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20380 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20390 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
203a0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
203b0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
203c0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
203d0 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
203e0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
203f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20400 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
20410 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
20420 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
20430 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
20440 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
20450 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
20460 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
20470 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
20480 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
20490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
204a0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
204b0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
204c0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
204d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
204e0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
204f0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
20500 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
20510 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
20520 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
20530 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
20540 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
20550 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
20560 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
20570 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
20580 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
20590 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
205a0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
205b0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
205c0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
205d0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
205e0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
205f0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
20600 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
20610 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
20620 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
20630 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
20640 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20650 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
20660 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
20670 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
20680 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
20690 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
206a0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
206b0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
206c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
206d0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
206e0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
206f0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
20700 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
20710 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
20720 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
20730 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
20740 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
20750 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
20760 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
20770 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
20780 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
20790 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
207a0 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
207b0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
207c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
207d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
207e0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
207f0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
20800 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
20810 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
20820 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
20830 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
20840 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
20850 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
20860 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
20870 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
20880 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
20890 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
208a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
208b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
208c0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
208d0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
208e0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
208f0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
20900 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
20910 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
20920 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
20930 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20940 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
20950 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
20960 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
20970 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
20980 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
20990 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
209a0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
209b0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
209c0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
209d0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
209e0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
209f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
20a00 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
20a10 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
20a20 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
20a30 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
20a40 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
20a50 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
20a60 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
20a70 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
20a80 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
20a90 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
20aa0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20ab0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
20ac0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
20ad0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
20ae0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
20af0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20b00 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
20b10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20b20 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20b30 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
20b40 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
20b50 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
20b60 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
20b70 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
20b80 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
20b90 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20ba0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
20bb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20bc0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20bd0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
20be0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
20bf0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
20c00 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
20c10 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
20c20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
20c30 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20c40 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
20c50 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
20c60 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
20c70 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
20c80 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20c90 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20ca0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20cb0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20cc0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
20cd0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
20ce0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
20cf0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20d00 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
20d10 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
20d20 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
20d30 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
20d40 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
20d50 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
20d60 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
20d70 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20d80 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20d90 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
20da0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
20db0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
20dc0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20dd0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
20de0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
20df0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
20e00 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
20e10 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
20e20 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
20e30 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
20e40 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
20e50 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
20e60 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
20e70 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
20e80 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
20e90 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
20ea0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
20eb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20ec0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
20ed0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
20ee0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
20ef0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
20f00 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
20f10 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
20f20 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
20f30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
20f40 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
20f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
20f60 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
20f70 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
20f80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20f90 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
20fa0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
20fb0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
20fc0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
20fd0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
20fe0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
20ff0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
21000 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
21010 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
21020 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21030 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
21040 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21050 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
21060 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
21070 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
21080 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
21090 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
210a0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
210b0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
210c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
210d0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
210e0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
210f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21100 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
21110 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
21120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21130 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
21140 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
21150 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
21160 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
21170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
21180 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
211a0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
211b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
211c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
211d0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
211e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
211f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
21200 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
21220 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
21230 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21240 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
21250 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
21260 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21270 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
21280 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
21290 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
212a0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
212b0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
212c0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
212d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
212e0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
212f0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
21300 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
21310 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
21320 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
21330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21340 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
21350 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21360 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
21370 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
21380 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
21390 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
213a0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
213b0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
213c0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
213d0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
213e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
213f0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
21400 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
21410 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
21420 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
21430 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
21440 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
21450 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
21460 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
21470 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
21480 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
21490 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
214a0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
214b0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
214c0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
214d0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
214e0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
214f0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
21500 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
21510 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
21520 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21530 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
21540 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
21550 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
21560 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
21570 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
21580 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
21590 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
215a0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
215b0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
215c0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
215d0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
215e0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
215f0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
21600 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
21610 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
21620 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
21630 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
21640 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
21650 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
21660 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
21670 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
21680 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21690 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
216a0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
216b0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
216c0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
216d0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
216e0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
216f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
21700 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
21710 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
21720 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
21730 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
21740 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
21750 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
21760 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
21770 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
21780 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
21790 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
217a0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
217b0 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
217c0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
217d0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
217e0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
217f0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
21800 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
21810 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
21820 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
21830 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
21840 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
21850 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
21860 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
21870 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
21880 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
21890 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
218a0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
218b0 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
218c0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
218d0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
218e0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
218f0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
21900 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
21910 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
21920 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
21930 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
21940 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
21950 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
21960 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
21970 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
21980 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
21990 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
219a0 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
219b0 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
219c0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
219d0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
219e0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
219f0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
21a00 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
21a10 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
21a20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
21a30 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
21a40 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
21a50 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
21a60 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
21a70 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
21a80 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
21a90 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
21aa0 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
21ab0 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
21ac0 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
21ad0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
21ae0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
21af0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
21b00 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
21b10 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
21b20 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
21b30 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
21b40 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
21b50 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
21b60 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
21b70 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
21b80 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
21b90 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
21ba0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
21bb0 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
21bc0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
21bd0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
21be0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
21bf0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
21c00 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
21c10 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
21c20 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
21c30 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
21c40 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
21c50 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
21c60 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
21c70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
21c80 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
21c90 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
21ca0 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
21cb0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
21cc0 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
21cd0 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
21ce0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
21cf0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
21d00 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
21d10 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
21d20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
21d30 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
21d40 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
21d50 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
21d60 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
21d70 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
21d80 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
21d90 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
21da0 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
21db0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
21dc0 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
21dd0 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
21de0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
21df0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
21e00 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
21e10 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
21e20 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
21e30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21e40 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
21e50 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
21e60 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
21e70 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
21e80 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
21e90 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
21ea0 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
21eb0 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
21ec0 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
21ed0 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
21ee0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
21ef0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
21f00 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
21f10 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21f20 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21f30 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
21f40 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
21f50 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
21f60 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
21f70 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
21f80 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
21f90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
21fa0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21fb0 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
21fc0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
21fd0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
21fe0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
21ff0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22000 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
22010 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
22020 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
22030 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
22040 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
22050 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
22060 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
22070 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
22080 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
22090 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
220a0 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
220b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
220c0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
220d0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
220e0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
220f0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
22100 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
22110 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
22120 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
22130 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
22140 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
22150 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
22160 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
22170 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
22180 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
22190 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
221a0 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
221b0 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
221c0 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
221d0 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
221e0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
221f0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22200 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22210 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22220 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
22230 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
22240 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22250 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
22260 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
22270 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22280 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
22290 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
222a0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
222b0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
222c0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
222d0 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
222e0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
222f0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22310 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
22320 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
22330 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
22340 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
22350 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
22360 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22370 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
22380 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
22390 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
223a0 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
223b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
223c0 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
223d0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
223e0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
223f0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
22400 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
22410 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
22420 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
22430 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
22440 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22450 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
22460 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
22470 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
22480 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
22490 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
224a0 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
224b0 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
224c0 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
224d0 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
224e0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
224f0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
22500 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
22510 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
22520 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
22530 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
22540 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
22550 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
22560 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
22570 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
22580 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
22590 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
225a0 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
225b0 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
225c0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
225d0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
225e0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
225f0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
22600 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
22610 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
22620 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
22630 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
22640 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
22650 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
22660 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
22670 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
22680 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
22690 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
226a0 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
226b0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
226c0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
226d0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
226e0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
226f0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
22700 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
22710 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
22720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22730 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
22740 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
22750 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
22760 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
22770 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
22780 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
22790 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
227a0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
227b0 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
227c0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
227d0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
227e0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
227f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
22800 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
22810 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
22820 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
22830 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
22840 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
22850 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
22860 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
22870 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
22880 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
22890 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
228a0 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
228b0 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
228c0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
228d0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
228e0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
228f0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
22900 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
22910 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
22920 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
22930 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
22940 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
22950 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
22960 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
22970 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
22980 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
22990 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
229a0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
229b0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
229c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
229d0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
229e0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
229f0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
22a00 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
22a10 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22a20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
22a30 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22a40 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
22a50 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22a60 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
22a70 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
22a80 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
22a90 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
22aa0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
22ab0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
22ac0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
22ad0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
22ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22af0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
22b00 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
22b10 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
22b20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22b30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22b40 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
22b50 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
22b60 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22b70 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
22b80 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
22b90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22ba0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
22bb0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22bc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22bd0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
22be0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
22bf0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
22c00 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
22c10 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22c20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
22c30 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
22c40 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
22c50 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
22c60 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
22c70 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
22c80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
22c90 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
22ca0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
22cb0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
22cc0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
22cd0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
22ce0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
22cf0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
22d00 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
22d10 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
22d20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
22d30 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
22d40 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
22d50 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
22d60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
22d70 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
22d80 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
22d90 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
22da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22db0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
22dc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22dd0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
22de0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
22df0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22e00 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
22e10 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
22e20 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
22e30 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
22e40 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
22e50 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22e60 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
22e70 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
22e80 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
22e90 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
22ea0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
22eb0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
22ec0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
22ed0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
22ee0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
22ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22f00 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22f10 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
22f20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
22f30 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
22f40 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
22f50 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
22f60 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
22f70 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
22f80 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
22f90 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
22fa0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
22fb0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22fc0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
22fd0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
22fe0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
22ff0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23000 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23010 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23020 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23030 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23040 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23050 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23060 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23070 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
23080 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23090 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
230a0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
230b0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
230c0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
230d0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
230e0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
230f0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23100 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23110 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23120 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23130 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23140 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23150 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23160 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
23170 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
23180 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23190 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
231a0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
231b0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
231c0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
231d0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
231e0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
231f0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23200 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23210 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23220 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23230 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23240 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23250 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23260 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
23270 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
23280 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
23290 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
232a0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
232b0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
232c0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
232d0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
232e0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
232f0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23300 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23310 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23320 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23330 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23340 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23350 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23360 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
23370 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
23380 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23390 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
233a0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
233b0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
233c0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
233d0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
233e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
233f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23400 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
23410 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
23420 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
23430 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
23440 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
23450 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
23460 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
23470 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
23480 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23490 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
234a0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
234b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
234c0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
234d0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
234e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
234f0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23500 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23510 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
23520 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
23530 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23540 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
23550 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23560 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
23570 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
23580 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
23590 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
235a0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
235b0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
235c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
235d0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
235e0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
235f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23600 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23610 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
23620 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
23630 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
23640 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
23650 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
23660 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
23670 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
23680 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
23690 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
236a0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
236b0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
236c0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
236d0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
236e0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
236f0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
23700 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23710 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
23720 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
23730 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
23740 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
23750 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
23760 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
23770 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
23780 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
23790 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
237a0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
237b0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
237c0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
237d0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
237e0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
237f0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23800 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
23810 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23820 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23830 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
23840 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
23850 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
23860 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23870 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
23880 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
23890 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
238a0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
238b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
238c0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
238d0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
238e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
238f0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
23900 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
23910 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23920 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
23930 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
23940 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
23950 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
23960 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23970 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23980 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
23990 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
239a0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
239b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
239c0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
239d0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
239e0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
239f0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
23a00 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23a10 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23a20 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
23a30 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
23a40 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23a50 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23a60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
23a70 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
23a80 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
23a90 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23aa0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23ab0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
23ac0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
23ad0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23ae0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
23af0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
23b00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23b10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23b20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
23b30 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
23b40 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
23b50 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23b60 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
23b70 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
23b80 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
23b90 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
23ba0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23bb0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
23bc0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
23bd0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
23be0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
23bf0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
23c00 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
23c10 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23c20 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23c30 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23c40 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
23c50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23c60 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
23c70 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
23c80 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
23c90 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
23ca0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23cb0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23cc0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
23cd0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
23ce0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
23cf0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
23d00 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
23d10 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
23d20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
23d30 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
23d40 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
23d50 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
23d60 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23d70 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23d80 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
23d90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23da0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23db0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
23dc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
23dd0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
23de0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
23df0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
23e00 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
23e10 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
23e20 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
23e30 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23e40 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
23e50 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
23e60 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
23e70 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
23e80 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23e90 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23ea0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23eb0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23ec0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
23ed0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23ee0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
23ef0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
23f00 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
23f10 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
23f20 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23f30 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
23f40 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
23f50 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
23f60 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
23f70 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
23f80 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
23f90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23fa0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23fb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23fc0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
23fd0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
23fe0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23ff0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
24000 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
24010 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
24020 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
24030 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
24040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
24050 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
24060 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
24070 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24080 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
24090 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
240a0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
240b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
240c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
240d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
240e0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
240f0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24100 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
24110 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
24120 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
24130 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24140 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
24150 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24160 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
24170 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24180 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
24190 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
241a0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
241b0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
241c0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
241d0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
241e0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
241f0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
24200 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
24210 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24220 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24230 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24240 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24250 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
24260 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
24270 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
24280 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
24290 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
242a0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
242b0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
242c0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
242d0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
242e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
242f0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
24300 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
24310 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
24320 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
24330 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24340 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
24350 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
24360 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
24370 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
24380 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
24390 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
243a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
243b0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
243c0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
243d0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
243e0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
243f0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
24400 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
24410 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24420 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
24430 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
24440 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
24450 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
24460 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
24470 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
24480 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
24490 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
244a0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
244b0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
244c0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
244d0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
244e0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
244f0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
24500 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
24510 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
24520 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
24530 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
24540 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
24550 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
24560 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
24570 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
24580 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24590 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
245a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
245b0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
245c0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
245d0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
245e0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
245f0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
24600 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
24610 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
24620 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
24630 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
24640 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
24650 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
24660 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
24670 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
24680 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
24690 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
246a0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
246b0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
246c0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
246d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
246e0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
246f0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
24700 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
24710 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
24720 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
24730 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
24740 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
24750 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
24760 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
24770 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
24780 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
24790 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
247a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
247b0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
247c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
247d0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
247e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
247f0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
24800 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
24810 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24820 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
24830 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
24840 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
24850 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
24860 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
24870 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
24880 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
24890 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
248a0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
248b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
248c0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
248d0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
248e0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
248f0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
24900 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
24910 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24920 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
24930 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
24940 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
24950 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
24960 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24980 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
24990 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
249a0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
249b0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
249c0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
249d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
249e0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
249f0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24a00 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24a10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24a20 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24a30 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24a40 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
24a50 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
24a60 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
24a70 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
24a80 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24a90 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24aa0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24ab0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24ac0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24ad0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24ae0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24af0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24b00 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24b10 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24b20 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24b30 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24b40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
24b50 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
24b60 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
24b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24b80 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24b90 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24ba0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24bb0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24bc0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24bd0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24be0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24bf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24c00 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24c10 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24c30 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24c40 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
24c50 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
24c60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
24c70 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
24c80 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24c90 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24ca0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24cb0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24cc0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24cd0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24ce0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24cf0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24d00 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24d10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24d20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
24d30 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
24d40 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
24d50 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
24d60 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
24d70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
24d80 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
24d90 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
24da0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24db0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24dc0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24dd0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24de0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24df0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24e00 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24e10 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24e20 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
24e30 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
24e40 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
24e50 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
24e60 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
24e70 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
24e80 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
24e90 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
24ea0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24eb0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24ec0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24ed0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24ee0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24ef0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24f00 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24f10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24f20 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
24f30 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
24f40 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
24f50 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
24f60 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
24f70 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
24f80 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
24f90 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
24fa0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
24fb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
24fc0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
24fd0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
24fe0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
24ff0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
25000 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
25010 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
25020 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25030 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
25040 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
25050 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
25060 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
25070 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
25080 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
25090 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
250a0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
250b0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
250c0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
250d0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
250e0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
250f0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
25100 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
25110 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
25120 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
25130 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
25140 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
25150 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
25160 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
25170 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
25180 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
25190 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
251a0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
251b0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
251c0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
251d0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
251e0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
251f0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
25200 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
25210 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25220 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25230 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25240 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25250 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25260 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
25270 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
25280 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
25290 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
252a0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
252b0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
252c0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
252d0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
252e0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
252f0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
25300 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
25310 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
25320 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
25330 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
25340 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
25350 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
25360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
25370 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
25380 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
25390 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
253a0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
253b0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
253c0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
253d0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
253e0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
253f0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
25400 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
25410 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
25420 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
25430 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
25440 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
25450 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
25460 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
25470 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
25480 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
25490 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
254a0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
254b0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
254c0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
254d0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
254e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
254f0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
25500 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25510 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
25520 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
25530 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
25540 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
25550 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25560 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
25570 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25580 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
25590 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
255a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
255b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
255c0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
255d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
255e0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
255f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25600 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
25610 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25620 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25630 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
25640 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
25650 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
25660 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
25670 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
25680 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
25690 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
256a0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
256b0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
256c0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
256d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
256e0 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
256f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25700 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
25710 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25720 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
25730 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
25740 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
25750 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25760 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25770 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
25780 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25790 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
257a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
257b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
257c0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
257d0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
257e0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
257f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25800 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
25810 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25820 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
25830 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25840 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
25850 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
25860 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
25870 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
25880 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
25890 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
258a0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
258b0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
258c0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
258d0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
258e0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
258f0 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
25900 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
25910 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25920 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
25930 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25940 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25960 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25970 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
25980 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
25990 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
259a0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
259b0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
259c0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
259d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
259e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
259f0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
25a00 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
25a10 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25a20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25a30 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
25a40 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
25a50 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25a60 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
25a70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25a80 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
25a90 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
25aa0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25ab0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
25ac0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
25ad0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25ae0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25af0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
25b00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25b10 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25b20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25b30 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
25b40 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
25b50 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
25b60 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
25b70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25b80 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
25b90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25ba0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25bb0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25bc0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25bd0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
25be0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
25bf0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25c00 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
25c10 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
25c20 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
25c30 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
25c40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25c50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
25c60 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
25c70 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
25c80 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
25c90 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
25ca0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
25cb0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
25cc0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
25cd0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
25ce0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
25cf0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
25d00 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
25d10 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
25d20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25d30 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
25d40 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
25d50 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25d60 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
25d70 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
25d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25d90 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25da0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
25db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25dc0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
25dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
25de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25df0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
25e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25e20 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
25e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
25e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25e50 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25e60 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
25e70 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
25e80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25e90 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
25ea0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
25eb0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25ec0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
25ed0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
25ee0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
25ef0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
25f00 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
25f10 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
25f20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
25f30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
25f40 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
25f50 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
25f60 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
25f70 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
25f80 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
25f90 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
25fa0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
25fb0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
25fc0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
25fd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
25fe0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
25ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26000 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
26010 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
26020 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
26030 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
26040 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
26050 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
26060 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
26070 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
26080 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
26090 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
260a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
260b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
260c0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
260d0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
260e0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
260f0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
26100 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
26110 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26120 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
26130 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
26140 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
26150 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
26160 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
26170 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26180 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
26190 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
261a0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
261b0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
261c0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
261d0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
261e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
261f0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
26200 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
26210 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
26220 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
26230 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
26240 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
26250 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
26260 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
26270 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
26280 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
26290 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
262a0 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
262b0 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
262c0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
262d0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
262e0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
262f0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
26300 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
26310 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
26320 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
26330 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
26340 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
26350 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
26360 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
26370 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
26380 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
26390 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
263a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
263b0 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
263c0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
263d0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
263e0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
263f0 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
26400 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
26410 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
26420 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
26430 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
26440 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
26450 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
26460 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
26470 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
26480 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
26490 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
264a0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
264b0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
264c0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
264d0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
264e0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
264f0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
26500 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
26510 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
26520 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
26530 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
26540 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
26550 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
26560 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26570 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
26580 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
26590 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
265a0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
265b0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
265c0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
265d0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
265e0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
265f0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
26600 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
26610 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
26620 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
26630 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
26640 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
26650 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
26660 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
26670 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
26680 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
26690 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
266a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
266b0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
266c0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
266d0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
266e0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
266f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
26700 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
26710 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
26720 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
26730 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
26740 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
26750 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
26760 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
26770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26780 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
26790 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
267a0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
267b0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
267c0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
267d0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
267e0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
267f0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
26800 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
26810 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
26820 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
26830 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
26840 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
26850 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
26860 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26870 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
26880 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
26890 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
268a0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
268b0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
268c0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
268d0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
268e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
268f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
26900 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
26910 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
26920 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
26930 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
26940 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
26950 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
26960 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
26970 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
26980 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
26990 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
269a0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
269b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
269c0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
269d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
269e0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
269f0 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
26a00 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
26a10 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
26a20 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
26a30 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
26a40 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
26a50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
26a60 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
26a70 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
26a80 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
26a90 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
26aa0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
26ab0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
26ac0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
26ad0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
26ae0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
26af0 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
26b00 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
26b10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26b20 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
26b30 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
26b40 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26b50 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
26b60 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
26b70 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
26b80 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
26b90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26ba0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
26bb0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
26bc0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
26bd0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
26be0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
26bf0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
26c00 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
26c10 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
26c20 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
26c30 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
26c40 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
26c50 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26c60 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
26c70 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
26c80 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
26c90 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
26ca0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
26cb0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
26cc0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
26cd0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
26ce0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
26cf0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
26d00 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
26d10 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
26d20 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
26d30 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
26d40 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
26d50 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
26d60 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
26d70 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
26d80 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
26d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26da0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
26db0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
26dc0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
26dd0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
26de0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
26df0 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
26e00 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
26e10 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
26e20 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
26e30 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
26e40 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
26e50 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
26e60 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
26e70 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
26e80 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
26e90 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
26ea0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
26eb0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
26ec0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
26ed0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
26ee0 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
26ef0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
26f00 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
26f10 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
26f20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
26f30 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
26f40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
26f50 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
26f60 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
26f70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26f80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26f90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26fa0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26fb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26fc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26fd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26fe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26ff0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27000 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27010 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27020 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27030 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
27040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27050 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
27060 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27070 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27080 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27090 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
270a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
270b0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
270c0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
270d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
270e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
270f0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27100 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27110 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
27120 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
27130 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
27140 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
27150 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
27160 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
27170 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27180 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
27190 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
271a0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
271b0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
271c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
271d0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
271e0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
271f0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
27200 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27210 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27220 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27230 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27240 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27250 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27260 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27270 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27280 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
27290 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
272a0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
272b0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
272c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
272d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
272e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
272f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27300 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27310 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27320 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27330 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27340 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
27350 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27360 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27370 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27380 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27390 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
273a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
273b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
273c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
273d0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
273e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
273f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27400 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27420 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
27430 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
27440 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
27450 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
27460 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
27470 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
27480 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
27490 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
274a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
274b0 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
274c0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
274d0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
274e0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
274f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27500 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27510 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
27520 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27530 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
27540 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27550 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
27560 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
27570 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
27580 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
27590 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
275a0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
275b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
275c0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
275d0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
275e0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
275f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
27600 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
27610 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
27620 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
27630 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
27640 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
27650 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
27660 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27670 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
27680 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
27690 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
276a0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
276b0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
276c0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
276d0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
276e0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
276f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
27700 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
27710 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
27720 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
27730 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
27740 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
27750 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27760 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
27770 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
27780 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
27790 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
277a0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
277b0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
277c0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
277d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
277e0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
277f0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27800 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
27810 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27820 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
27830 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
27840 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
27850 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
27860 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
27870 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
27880 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
27890 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
278a0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
278b0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
278c0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
278d0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
278e0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
278f0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
27900 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
27910 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
27920 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
27930 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
27940 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
27950 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
27960 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
27970 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
27980 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
27990 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
279a0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
279b0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
279c0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
279d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
279e0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
279f0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
27a00 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
27a10 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
27a20 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
27a30 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
27a40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
27a50 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
27a60 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
27a70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27a80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
27a90 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
27aa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27ab0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
27ac0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
27ae0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
27af0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
27b00 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
27b10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27b20 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
27b30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27b40 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27b50 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
27b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27b70 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
27b80 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
27b90 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27ba0 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
27bb0 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
27bc0 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
27bd0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
27be0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
27bf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
27c00 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
27c10 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
27c20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27c30 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
27c40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
27c50 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
27c60 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
27c70 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
27c80 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
27c90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27ca0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
27cb0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27cc0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
27cd0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
27ce0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
27cf0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27d00 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
27d10 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
27d20 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
27d30 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
27d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27d50 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
27d60 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
27d70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
27d80 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
27d90 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
27da0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
27db0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
27dc0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
27dd0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
27de0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
27df0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
27e00 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
27e10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
27e20 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
27e30 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
27e40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
27e50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
27e60 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
27e70 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
27e80 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
27e90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27ea0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
27eb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
27ec0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
27ed0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
27ee0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
27ef0 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
27f00 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
27f10 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
27f20 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
27f30 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
27f40 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
27f50 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
27f60 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
27f70 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
27f80 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
27f90 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
27fa0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
27fb0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
27fc0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
27fd0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
27fe0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27ff0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
28000 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
28010 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
28020 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
28030 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
28040 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28050 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
28060 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
28070 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
28080 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
28090 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
280a0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
280b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
280c0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
280d0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
280e0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
280f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
28100 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
28110 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28120 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
28130 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
28140 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
28150 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
28160 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
28170 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
28180 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
28190 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
281a0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
281b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
281c0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
281d0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
281e0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
281f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
28200 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
28210 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
28220 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
28230 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
28240 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
28250 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
28260 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
28270 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
28280 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
28290 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
282a0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
282b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
282c0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
282d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
282e0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
282f0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
28300 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
28310 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
28320 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
28330 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28340 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
28350 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
28360 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
28370 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
28380 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
28390 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
283a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
283b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
283c0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
283d0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
283e0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
283f0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
28400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28410 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
28420 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
28430 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
28440 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28450 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
28460 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
28470 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
28480 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
28490 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
284a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
284b0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
284c0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
284d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
284e0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
284f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28500 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
28510 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
28520 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
28530 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28540 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
28550 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
28560 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
28570 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28580 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
28590 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
285a0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
285b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
285c0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
285d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
285e0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
285f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28600 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
28610 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
28620 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
28630 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
28640 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
28650 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
28660 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
28670 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
28680 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
28690 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
286a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
286b0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
286c0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
286d0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
286e0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
286f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
28700 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28710 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
28720 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
28730 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28740 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
28750 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
28760 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
28770 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
28780 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28790 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
287a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
287b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
287c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
287d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
287e0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
287f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
28800 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
28810 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28820 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
28830 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28840 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
28850 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28860 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
28870 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
28880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
28890 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
288a0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
288b0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
288c0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
288d0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
288e0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
288f0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
28900 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
28910 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
28920 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
28930 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
28940 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
28950 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
28960 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
28970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
28980 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
28990 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
289a0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
289b0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
289c0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
289d0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
289e0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
289f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
28a00 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
28a10 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
28a20 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
28a30 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
28a40 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
28a50 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
28a60 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
28a70 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
28a80 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
28a90 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
28aa0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
28ab0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
28ac0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
28ad0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
28ae0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
28af0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
28b00 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
28b10 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
28b20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
28b30 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28b40 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
28b50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
28b60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
28b70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28b80 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
28b90 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
28ba0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
28bb0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
28bc0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
28bd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28be0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
28bf0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
28c00 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
28c10 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
28c20 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
28c30 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
28c40 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
28c50 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
28c60 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
28c70 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
28c80 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
28c90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
28ca0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
28cb0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
28cc0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
28cd0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
28ce0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
28cf0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
28d00 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
28d10 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
28d20 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
28d30 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
28d40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
28d50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
28d60 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
28d70 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
28d80 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
28d90 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
28da0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
28db0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
28dc0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
28dd0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
28de0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
28df0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
28e00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
28e10 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
28e20 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
28e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
28e40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
28e50 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
28e60 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
28e70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
28e80 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
28e90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28ea0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
28eb0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
28ec0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28ed0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
28ee0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
28ef0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28f00 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
28f10 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
28f20 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
28f30 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
28f40 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
28f50 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
28f60 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
28f70 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
28f80 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
28f90 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
28fa0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
28fb0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
28fc0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
28fd0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28fe0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
28ff0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
29000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
29010 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
29020 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
29030 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29040 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
29050 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
29060 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
29070 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
29080 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
29090 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
290a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
290b0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
290c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
290d0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
290e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
290f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29100 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
29110 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
29120 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
29130 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
29140 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
29150 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
29160 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
29170 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
29180 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
29190 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
291a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
291b0 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
291c0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
291d0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
291e0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
291f0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
29200 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
29210 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
29220 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
29230 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
29240 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
29250 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
29260 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
29270 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
29280 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29290 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
292a0 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
292b0 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
292c0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
292d0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
292e0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
292f0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
29300 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
29310 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
29320 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
29330 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
29340 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
29350 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
29360 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
29370 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
29380 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
29390 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
293a0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
293b0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
293c0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
293d0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
293e0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
293f0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
29400 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
29410 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
29420 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
29430 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29440 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
29450 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
29460 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
29470 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
29480 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
29490 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
294a0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
294b0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
294c0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
294d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
294e0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
294f0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
29500 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
29510 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
29520 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
29530 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29540 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
29550 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
29560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29570 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
29590 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
295a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
295b0 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
295c0 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
295d0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
295e0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
295f0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
29600 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
29610 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
29620 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
29630 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
29640 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
29650 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
29660 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
29670 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
29680 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
29690 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
296a0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
296b0 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
296c0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
296d0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
296e0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
296f0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
29700 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
29710 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
29720 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
29730 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29740 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
29750 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
29760 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
29770 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
29780 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
29790 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
297a0 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
297b0 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
297c0 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
297d0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
297e0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
297f0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
29800 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
29810 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
29820 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
29830 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
29840 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
29850 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
29860 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
29870 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
29880 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
29890 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
298a0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
298b0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
298c0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
298d0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
298e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
298f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
29900 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
29910 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
29920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
29930 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
29940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
29950 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
29960 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
29970 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
29980 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
29990 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
299a0 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
299b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
299c0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
299d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
299e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
299f0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
29a00 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
29a10 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
29a20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29a30 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
29a40 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
29a50 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
29a60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
29a70 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
29a80 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
29a90 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
29aa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
29ab0 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
29ac0 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
29ad0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
29ae0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
29af0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29b00 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
29b10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
29b20 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
29b30 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
29b40 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
29b50 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
29b60 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
29b70 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
29b80 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
29b90 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
29ba0 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
29bb0 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
29bc0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
29bd0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
29be0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
29bf0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
29c00 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
29c10 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
29c20 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
29c30 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
29c40 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
29c50 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
29c60 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
29c70 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
29c80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29c90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29ca0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
29cb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29cc0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
29cd0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
29ce0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
29cf0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
29d00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29d10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29d20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
29d30 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
29d40 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
29d50 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36  lite3_bind_blob6
29d60 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
29d70 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29d80 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
29d90 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
29da0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
29db0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
29dc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
29dd0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
29de0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
29df0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29e00 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
29e10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
29e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29e30 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
29e40 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
29e50 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
29e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
29e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e80 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
29e90 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
29ea0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
29eb0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
29ec0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
29ed0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29ee0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
29ef0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29f00 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
29f10 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
29f20 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
29f30 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  ext64(sqlite3_st
29f40 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29f50 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75  char*, sqlite3_u
29f60 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
29f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29f80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20  void(*)(void*), 
29f90 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e  unsigned char en
29fa0 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c  coding);.int sql
29fb0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29fc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29fd0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
29fe0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
29ff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2a000 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2a010 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
2a020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a030 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
2a040 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
2a050 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2a060 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2a070 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2a080 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2a090 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2a0a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2a0b0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2a0c0 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2a0d0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2a0e0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2a0f0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2a100 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2a110 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2a120 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2a130 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2a140 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2a150 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2a160 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2a170 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2a180 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2a190 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2a1a0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2a1b0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2a1c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2a1d0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2a1e0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2a1f0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2a200 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2a210 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2a220 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2a230 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2a240 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2a250 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2a260 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2a270 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2a280 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2a290 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a2a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2a2b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a2c0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2a2d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a2e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2a2f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2a300 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a310 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2a320 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a330 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2a340 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2a350 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
2a360 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a370 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2a380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2a390 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2a3a0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2a3b0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2a3c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a3d0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2a3e0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2a3f0 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2a400 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2a410 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2a420 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2a430 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2a440 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2a450 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2a460 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2a470 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2a480 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2a490 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2a4a0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2a4b0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2a4c0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2a4d0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2a4e0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2a4f0 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2a500 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2a510 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2a520 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2a530 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2a540 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2a550 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2a560 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2a570 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2a580 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2a590 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2a5a0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2a5b0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2a5c0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2a5d0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2a5e0 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2a5f0 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2a600 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2a610 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2a620 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2a630 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2a640 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2a650 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2a660 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2a670 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2a680 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2a690 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a6a0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2a6b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a6c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a6d0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a6e0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a6f0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a700 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a710 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a720 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a730 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a740 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a750 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2a760 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2a770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2a780 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2a790 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2a7a0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
2a7b0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2a7c0 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2a7d0 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2a7e0 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2a7f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2a800 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2a810 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2a820 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2a830 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a840 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2a850 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2a860 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2a870 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2a880 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2a890 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2a8a0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2a8b0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2a8c0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2a8d0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2a8e0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2a8f0 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2a900 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2a910 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2a920 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a930 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2a940 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2a950 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2a960 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2a970 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2a980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a990 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2a9a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a9b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a9c0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
2a9d0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
2a9e0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
2a9f0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2aa00 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
2aa10 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2aa20 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
2aa30 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2aa40 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2aa50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2aa60 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2aa70 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2aa80 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2aa90 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2aaa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2aab0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2aac0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2aad0 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2aae0 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
2aaf0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
2ab00 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2ab10 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2ab20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2ab30 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
2ab40 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2ab50 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
2ab60 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2ab70 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2ab80 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
2ab90 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2aba0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
2abb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2abc0 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
2abd0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
2abe0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
2abf0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
2ac00 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
2ac10 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
2ac20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2ac30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
2ac40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2ac50 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
2ac60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ac70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac80 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
2ac90 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2aca0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2acb0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2acc0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
2acd0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
2ace0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
2acf0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2ad00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2ad10 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
2ad20 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
2ad30 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2ad40 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ad50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2ad60 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
2ad70 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
2ad80 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
2ad90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2ada0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2adb0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
2adc0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
2add0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2ade0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2adf0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
2ae00 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2ae10 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ae20 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
2ae30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ae40 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
2ae50 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
2ae60 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
2ae70 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
2ae80 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2ae90 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
2aea0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
2aeb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2aec0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
2aed0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
2aee0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2aef0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2af00 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2af10 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2af20 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2af30 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2af40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2af50 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2af60 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2af70 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
2af80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2af90 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
2afa0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2afb0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
2afc0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
2afd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
2afe0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
2aff0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
2b000 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
2b010 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
2b020 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
2b030 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
2b040 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
2b050 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2b060 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2b070 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2b080 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
2b090 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2b0a0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
2b0b0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
2b0c0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
2b0d0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
2b0e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
2b0f0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
2b100 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2b110 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
2b120 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
2b130 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
2b140 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
2b150 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
2b160 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2b180 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2b190 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
2b1a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b1b0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2b1c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b1d0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2b1e0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2b1f0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2b200 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
2b210 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2b220 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2b230 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2b240 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2b250 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2b260 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2b270 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2b280 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2b290 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2b2a0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2b2b0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2b2c0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2b2d0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2b2e0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2b2f0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2b300 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2b310 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2b320 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2b330 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2b340 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2b350 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2b360 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2b370 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2b380 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2b390 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2b3a0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2b3b0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2b3c0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2b3d0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2b3e0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2b3f0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2b400 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b410 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2b420 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2b430 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2b440 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2b450 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2b460 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b470 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2b480 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2b490 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2b4a0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2b4b0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2b4c0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2b4d0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2b4e0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2b4f0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2b500 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2b510 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2b520 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2b530 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2b540 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2b550 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2b560 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2b570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b580 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2b590 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2b5a0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2b5b0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2b5c0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2b5d0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2b5e0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2b5f0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2b600 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2b610 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2b620 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2b630 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2b640 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2b650 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2b660 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2b670 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2b680 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2b690 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2b6a0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2b6b0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2b6c0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2b6d0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2b6e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2b6f0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2b700 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2b710 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2b720 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2b730 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2b740 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2b750 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2b760 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2b770 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2b780 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2b790 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2b7a0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2b7b0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2b7c0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2b7d0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2b7e0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2b7f0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2b800 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2b810 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2b820 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2b830 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2b840 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2b850 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2b860 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2b870 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2b880 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2b890 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2b8a0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2b8b0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2b8c0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2b8d0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2b8e0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2b8f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2b900 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2b910 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b920 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2b930 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2b940 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2b950 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2b960 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2b970 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2b980 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2b990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2b9a0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2b9b0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2b9c0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2b9d0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2b9e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b9f0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2ba00 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2ba10 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2ba20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ba30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
2ba40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ba50 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2ba60 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2ba70 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2ba80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2ba90 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2baa0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2bab0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bac0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2bad0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2bae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2baf0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2bb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bb10 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
2bb20 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bb30 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bb40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2bb50 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2bb60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2bb70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2bb80 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2bb90 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2bba0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2bbb0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
2bbc0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
2bbd0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2bbe0 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
2bbf0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
2bc00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bc10 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
2bc20 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
2bc30 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2bc40 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
2bc50 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
2bc60 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
2bc70 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
2bc80 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
2bc90 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
2bca0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2bcb0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
2bcc0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
2bcd0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
2bce0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
2bcf0 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
2bd00 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
2bd10 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
2bd20 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2bd30 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
2bd40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2bd50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
2bd60 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2bd70 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
2bd80 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
2bd90 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2bda0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
2bdb0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
2bdc0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
2bdd0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
2bde0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
2bdf0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
2be00 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2be10 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
2be20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
2be30 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
2be40 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
2be50 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
2be60 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
2be70 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
2be80 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
2be90 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
2bea0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
2beb0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
2bec0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
2bed0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
2bee0 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
2bef0 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
2bf00 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
2bf10 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
2bf20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
2bf30 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
2bf40 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
2bf50 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
2bf60 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
2bf70 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
2bf80 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
2bf90 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
2bfa0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
2bfb0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
2bfc0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
2bfd0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
2bfe0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
2bff0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
2c000 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
2c010 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
2c020 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
2c030 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
2c040 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c050 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
2c060 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2c070 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2c090 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
2c0a0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2c0b0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
2c0c0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
2c0d0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
2c0e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c0f0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2c100 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2c110 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2c120 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c130 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c140 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2c150 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2c160 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2c170 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c190 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2c1a0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2c1b0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2c1c0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2c1d0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2c1e0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2c1f0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2c200 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2c210 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2c220 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2c230 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2c240 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2c250 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2c260 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2c270 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2c280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c290 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2c2a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c2b0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2c2c0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2c2d0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2c2e0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2c2f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c300 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2c310 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2c320 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2c330 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2c340 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2c350 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2c360 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2c370 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2c380 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2c390 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2c3a0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2c3b0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2c3c0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2c3d0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2c3e0 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2c3f0 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2c400 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2c410 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2c420 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2c430 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2c440 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2c450 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2c460 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2c470 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2c480 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2c490 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2c4a0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2c4b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2c4c0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2c4d0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2c4e0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2c4f0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2c500 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2c510 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c520 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2c530 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2c540 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2c550 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2c560 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2c570 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2c580 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2c590 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2c5a0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2c5b0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2c5c0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2c5d0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2c5e0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2c5f0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2c600 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2c610 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2c620 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2c630 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2c640 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2c650 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2c660 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2c670 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2c680 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2c690 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2c6a0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2c6b0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2c6c0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2c6d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2c6e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2c6f0 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2c700 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2c710 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2c720 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2c730 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2c740 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2c750 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2c760 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2c770 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2c780 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2c790 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2c7a0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2c7b0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2c7c0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
2c7d0 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
2c7e0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2c7f0 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
2c800 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
2c810 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
2c820 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
2c830 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
2c840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
2c850 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
2c860 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
2c870 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
2c880 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
2c890 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
2c8a0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2c8b0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2c8c0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
2c8d0 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
2c8e0 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
2c8f0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2c900 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
2c910 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
2c920 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c930 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
2c940 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
2c950 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
2c960 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
2c970 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
2c980 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
2c990 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
2c9a0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
2c9b0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
2c9c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c9d0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
2c9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c9f0 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
2ca00 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
2ca10 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2ca20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
2ca30 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
2ca40 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2ca50 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
2ca60 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
2ca70 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
2ca80 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
2ca90 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
2caa0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
2cab0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
2cac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cad0 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
2cae0 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
2caf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
2cb00 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
2cb10 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
2cb20 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
2cb30 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
2cb40 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
2cb50 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
2cb60 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
2cb70 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
2cb80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cb90 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
2cba0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
2cbb0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
2cbc0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
2cbd0 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
2cbe0 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
2cbf0 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
2cc00 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
2cc10 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
2cc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2cc30 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
2cc40 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
2cc50 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
2cc60 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
2cc70 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2cc80 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
2cc90 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
2cca0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
2ccb0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
2ccc0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
2ccd0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2cce0 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
2ccf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cd00 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
2cd10 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
2cd20 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
2cd30 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2cd40 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
2cd50 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
2cd60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
2cd70 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
2cd80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cd90 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
2cda0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
2cdb0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
2cdc0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
2cdd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2cde0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
2cdf0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
2ce00 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
2ce10 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
2ce20 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
2ce30 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
2ce40 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
2ce50 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
2ce60 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
2ce70 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2ce80 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
2ce90 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
2cea0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
2ceb0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
2cec0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
2ced0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
2cee0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
2cef0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
2cf00 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
2cf10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
2cf20 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
2cf30 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
2cf40 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
2cf50 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
2cf60 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
2cf70 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2cf80 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
2cf90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2cfa0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
2cfb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cfc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2cfd0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
2cfe0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
2cff0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
2d000 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2d010 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
2d020 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
2d030 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
2d040 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
2d050 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
2d060 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
2d070 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
2d080 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2d090 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
2d0a0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
2d0b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
2d0c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
2d0d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d0e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
2d0f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d100 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
2d110 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
2d120 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2d130 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2d140 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
2d150 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
2d160 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
2d170 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
2d180 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2d190 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
2d1a0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
2d1b0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
2d1c0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2d1d0 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
2d1e0 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2d1f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2d200 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2d210 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2d220 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2d230 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d240 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2d250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2d270 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2d280 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2d290 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2d2a0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2d2b0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2d2c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d2d0 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2d2e0 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2d2f0 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2d300 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2d310 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d320 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2d330 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2d340 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2d350 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2d360 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2d370 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2d380 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d390 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2d3a0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2d3b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2d3c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d3d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2d3e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2d3f0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2d400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d410 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2d420 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2d430 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2d440 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2d450 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2d460 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2d470 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2d480 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2d490 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2d4a0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2d4b0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2d4c0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2d4d0 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2d4e0 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2d4f0 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2d500 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2d510 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2d520 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2d530 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2d540 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2d550 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2d560 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2d570 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2d580 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2d590 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d5a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d5b0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2d5c0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
2d5d0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2d5e0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
2d5f0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
2d600 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
2d610 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
2d620 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
2d630 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
2d640 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2d650 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
2d660 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
2d670 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
2d680 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
2d690 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
2d6a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
2d6b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2d6c0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2d6d0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2d6e0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2d6f0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2d700 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2d710 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2d720 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2d730 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2d740 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2d750 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2d760 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2d770 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2d780 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2d790 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d7a0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2d7b0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2d7c0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2d7d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2d7e0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2d7f0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2d800 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2d810 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2d820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2d830 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2d840 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2d850 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2d860 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2d870 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2d880 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2d890 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2d8a0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2d8b0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2d8c0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
2d8d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2d8e0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2d8f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2d900 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2d910 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2d920 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
2d930 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2d940 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
2d950 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
2d960 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
2d970 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
2d980 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
2d990 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
2d9a0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
2d9b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2d9c0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
2d9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d9e0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
2d9f0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
2da00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
2da10 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
2da20 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
2da30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2da40 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
2da50 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
2da60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2da70 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2da80 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
2da90 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
2daa0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
2dab0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
2dac0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2dad0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2dae0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
2daf0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
2db00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2db10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
2db20 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
2db30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2db40 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2db50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2db60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
2db70 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
2db80 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
2db90 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
2dba0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
2dbb0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
2dbc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
2dbd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
2dbe0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
2dbf0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2dc00 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
2dc10 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2dc20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2dc30 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
2dc40 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
2dc50 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2dc60 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
2dc70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2dc80 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
2dc90 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
2dca0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
2dcb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2dcc0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
2dcd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dce0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2dcf0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2dd00 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
2dd10 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2dd20 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
2dd30 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
2dd40 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
2dd50 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2dd60 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
2dd70 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2dd80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2dd90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2dda0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
2ddb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
2ddc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
2ddd0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
2dde0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2ddf0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
2de00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2de10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2de20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2de30 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
2de40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
2de50 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
2de60 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
2de70 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
2de80 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
2de90 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
2dea0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
2deb0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
2dec0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
2ded0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
2dee0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
2def0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
2df00 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
2df10 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
2df20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
2df30 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2df40 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
2df50 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
2df60 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
2df70 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
2df80 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
2df90 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
2dfa0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2dfb0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
2dfc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2dfd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2dfe0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
2dff0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
2e000 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
2e010 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
2e020 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2e030 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
2e040 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
2e050 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
2e060 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2e070 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2e080 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
2e090 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2e0a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2e0b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2e0c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e0d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2e0e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2e0f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e100 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2e110 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2e120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2e130 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2e140 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2e150 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2e160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e170 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2e180 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2e190 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2e1a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e1b0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
2e1c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2e1d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2e1e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2e1f0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
2e200 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2e210 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e220 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
2e230 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e240 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
2e250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e260 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
2e270 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
2e280 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2e290 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
2e2a0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2e2b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e2c0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
2e2d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e2e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2e2f0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2e300 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2e310 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2e320 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
2e330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e340 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
2e350 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2e360 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
2e370 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2e380 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2e390 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e3a0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2e3b0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2e3c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e3d0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2e3e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2e3f0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2e400 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
2e410 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e420 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2e430 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2e440 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2e450 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e460 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2e470 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e480 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
2e490 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
2e4a0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
2e4b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e4c0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
2e4d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e4e0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
2e4f0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
2e500 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
2e510 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2e520 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
2e530 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2e540 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2e550 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e560 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2e570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
2e580 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
2e590 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
2e5a0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2e5b0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2e5c0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2e5d0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
2e5e0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
2e5f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e600 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
2e610 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e620 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
2e630 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
2e640 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
2e650 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
2e660 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2e670 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2e680 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2e690 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2e6a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e6b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
2e6c0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
2e6d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e6e0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
2e6f0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2e700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e710 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
2e720 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e730 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
2e740 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2e750 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
2e760 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2e770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2e780 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2e790 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2e7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e7b0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2e7c0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2e7d0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2e7e0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2e7f0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2e800 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2e810 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2e820 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2e830 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e840 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2e850 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e860 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
2e870 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2e880 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e890 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2e8a0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2e8b0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2e8c0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2e8d0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2e8e0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2e8f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2e900 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2e910 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2e920 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2e930 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e940 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2e950 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2e960 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2e970 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2e980 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2e990 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2e9a0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2e9b0 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2e9c0 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2e9d0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2e9e0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2e9f0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2ea00 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2ea10 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2ea20 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2ea30 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2ea40 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2ea50 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2ea60 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2ea70 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2ea80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2ea90 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2eaa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2eab0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2eac0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2ead0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2eae0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2eaf0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2eb00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2eb10 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2eb20 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2eb30 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2eb40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2eb50 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2eb60 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2eb70 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2eb80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2eb90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2eba0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2ebb0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2ebc0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2ebd0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2ebe0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2ebf0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2ec00 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2ec10 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2ec20 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2ec30 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2ec40 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2ec50 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2ec60 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2ec70 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2ec80 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2ec90 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
2eca0 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
2ecb0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2ecc0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2ecd0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2ece0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2ecf0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ed00 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ed10 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2ed20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ed30 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2ed40 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2ed50 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2ed60 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2ed70 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2ed80 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2ed90 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2eda0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2edb0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2edc0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2edd0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2ede0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2edf0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2ee00 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2ee10 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2ee20 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2ee30 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2ee40 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2ee50 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2ee60 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2ee70 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2ee80 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2ee90 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2eea0 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2eeb0 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2eec0 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2eed0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2eee0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2eef0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2ef00 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2ef10 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2ef20 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2ef30 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2ef40 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2ef50 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2ef60 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2ef70 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2ef80 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2ef90 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2efa0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2efb0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2efc0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2efd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2efe0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2eff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f000 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2f010 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2f020 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2f030 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2f040 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2f050 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2f060 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2f070 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2f080 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f090 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2f0a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2f0b0 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2f0c0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2f0d0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2f0e0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2f0f0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2f100 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2f110 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2f120 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2f130 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2f140 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2f150 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2f160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f170 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2f180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f190 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2f1a0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2f1b0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2f1c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2f1d0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2f1e0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2f1f0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2f200 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2f210 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2f220 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2f230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2f240 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2f250 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2f260 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2f270 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2f280 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2f290 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2f2a0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2f2b0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2f2c0 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2f2d0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2f2e0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2f2f0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2f300 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2f310 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2f320 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2f330 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2f340 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2f350 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2f360 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2f370 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2f380 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2f390 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2f3a0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2f3b0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2f3c0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2f3d0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2f3e0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2f3f0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2f400 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2f410 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2f420 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2f430 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2f440 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2f450 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2f460 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2f470 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f480 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2f490 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2f4a0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2f4b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2f4c0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2f4d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f4e0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2f4f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f500 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2f510 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2f520 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2f530 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f540 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2f550 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2f560 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2f570 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2f580 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2f590 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2f5a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f5b0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2f5c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2f5d0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2f5e0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2f5f0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2f600 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2f610 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f620 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2f630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f640 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2f650 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2f660 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2f670 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2f680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f690 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f6a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2f6b0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2f6c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f6d0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2f6e0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2f6f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f700 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2f710 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2f720 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2f740 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2f750 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2f760 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2f770 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2f780 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2f790 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2f7a0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2f7b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2f7c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2f7d0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2f7e0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2f7f0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2f800 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2f810 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2f820 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2f830 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2f840 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2f850 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
2f860 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
2f870 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2f880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f890 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2f8a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2f8b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2f8c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2f8d0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2f8e0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2f8f0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2f900 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2f910 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2f920 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2f930 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2f940 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2f950 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2f960 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2f970 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2f980 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2f990 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2f9a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2f9b0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2f9c0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2f9d0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2f9e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f9f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2fa00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fa10 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2fa20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fa30 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2fa40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2fa50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2fa60 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2fa70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fa80 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2fa90 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2faa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2fab0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2fac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2fad0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fae0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2faf0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2fb00 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2fb10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fb20 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2fb30 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2fb40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fb50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fb60 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2fb70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2fb80 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2fb90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2fba0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2fbb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2fbc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2fbd0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2fbe0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2fbf0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2fc00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2fc10 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2fc20 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2fc30 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2fc40 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2fc50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2fc60 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2fc70 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2fc80 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2fc90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2fca0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2fcb0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2fcc0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2fcd0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2fce0 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2fcf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2fd00 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2fd10 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2fd20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2fd30 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2fd40 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2fd50 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2fd60 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2fd70 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2fd80 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2fd90 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2fda0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2fdb0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2fdc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2fdd0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2fde0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2fdf0 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2fe00 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2fe10 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2fe20 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2fe30 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2fe40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2fe50 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2fe60 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2fe70 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2fe80 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2fe90 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2fea0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2feb0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2fec0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2fed0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2fee0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2fef0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2ff00 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2ff10 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2ff20 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2ff30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2ff40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ff50 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2ff60 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2ff70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2ff80 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2ff90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ffa0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2ffb0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2ffc0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2ffd0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2ffe0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2fff0 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
30000 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
30010 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
30020 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
30030 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
30040 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
30050 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
30060 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
30070 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
30080 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
30090 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
300a0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
300b0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
300c0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
300d0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
300e0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
300f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
30100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30110 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
30120 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
30130 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
30140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
30150 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
30160 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
30170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30180 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
30190 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
301a0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
301b0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
301c0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
301d0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
301e0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
301f0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
30200 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
30210 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
30220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
30230 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
30240 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
30250 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
30260 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
30270 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
30280 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
30290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
302a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
302b0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
302c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
302d0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
302e0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
302f0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
30300 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
30310 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30320 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
30330 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
30340 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
30350 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
30360 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
30370 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
30380 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
30390 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
303a0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
303b0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
303c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
303d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
303e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
303f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
30410 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
30420 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30430 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
30440 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
30450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30460 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
30470 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
30480 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
30490 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
304a0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
304b0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
304c0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
304d0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
304e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
304f0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
30500 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30510 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
30520 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
30530 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30550 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
30560 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
30570 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
30580 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
30590 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
305a0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
305b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
305c0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
305d0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
305e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
305f0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
30600 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
30610 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
30620 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
30630 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
30640 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
30650 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
30660 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
30670 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
30680 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
30690 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
306a0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
306b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
306c0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
306d0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
306e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
306f0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
30700 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
30710 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
30720 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
30730 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
30740 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
30750 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
30760 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
30770 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
30780 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
30790 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
307a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
307b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
307c0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
307d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
307e0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
307f0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
30800 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
30810 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
30820 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
30830 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
30840 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
30850 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
30860 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30870 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
30880 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
30890 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
308a0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
308b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
308c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
308d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
308e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
308f0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
30900 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
30910 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
30920 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
30930 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
30940 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
30950 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
30960 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
30970 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
30980 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
30990 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
309a0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
309b0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
309c0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
309d0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
309e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
309f0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
30a00 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
30a10 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
30a20 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
30a30 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
30a40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30a50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30a60 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
30a70 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
30a80 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
30a90 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
30aa0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
30ab0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
30ac0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
30ad0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30ae0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
30af0 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
30b00 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
30b10 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
30b20 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
30b30 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
30b40 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
30b50 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
30b60 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
30b70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
30b80 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
30b90 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
30ba0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
30bb0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
30bc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
30bd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
30be0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
30bf0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
30c00 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
30c10 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
30c20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
30c30 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
30c40 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
30c50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
30c60 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
30c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
30c80 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
30c90 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
30ca0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
30cb0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
30cc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30cd0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
30ce0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
30cf0 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
30d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
30d10 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
30d20 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
30d30 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
30d40 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
30d50 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
30d60 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
30d70 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
30d80 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
30d90 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
30da0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
30db0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
30dc0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
30dd0 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
30de0 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
30df0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
30e00 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
30e10 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
30e20 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
30e30 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
30e40 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
30e50 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
30e60 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
30e70 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
30e80 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
30e90 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
30ea0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
30eb0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
30ec0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
30ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30ee0 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
30ef0 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
30f00 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
30f10 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
30f20 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
30f30 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
30f40 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
30f50 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
30f60 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
30f70 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
30f80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
30f90 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
30fa0 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
30fb0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
30fc0 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
30fd0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
30fe0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
30ff0 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
31000 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
31010 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
31020 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
31030 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
31040 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
31050 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
31060 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
31070 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
31080 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
31090 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
310a0 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
310b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
310c0 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
310d0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
310e0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
310f0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
31100 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
31110 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
31120 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
31130 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
31140 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
31150 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31160 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
31170 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
31180 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
31190 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
311a0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
311b0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
311c0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
311d0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
311e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
311f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
31200 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
31210 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
31220 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
31230 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
31240 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
31250 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
31260 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
31270 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
31280 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
31290 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
312a0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
312b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
312c0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
312d0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
312e0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
312f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
31300 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
31310 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
31320 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
31330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
31340 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
31350 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
31360 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
31370 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
31380 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
31390 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
313a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
313b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
313c0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
313d0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
313e0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
313f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
31400 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
31410 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
31420 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
31430 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
31440 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
31450 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
31460 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
31470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31480 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
31490 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
314a0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
314b0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
314c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
314d0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
314e0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
314f0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31500 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
31510 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
31520 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
31530 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
31540 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
31550 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
31560 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31570 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
31580 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
31590 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
315a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
315b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
315c0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
315d0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
315e0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
315f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
31600 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
31610 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
31620 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
31630 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
31640 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
31650 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
31660 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
31670 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
31680 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
31690 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
316a0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
316b0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
316c0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
316d0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
316e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
316f0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
31700 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
31710 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
31720 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
31730 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
31740 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
31750 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
31760 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
31770 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
31780 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
31790 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
317a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
317b0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
317c0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
317d0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
317e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
317f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
31800 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
31810 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
31820 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
31830 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
31840 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
31850 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
31860 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
31870 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
31880 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
31890 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
318a0 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
318b0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
318c0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
318d0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
318e0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
318f0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
31900 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31910 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
31920 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31930 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
31940 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
31950 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
31960 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
31970 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
31980 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
31990 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
319a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
319b0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
319c0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
319d0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
319e0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
319f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31a00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31a10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
31a20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
31a30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31a40 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31a50 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31a60 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31a70 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
31a80 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31a90 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31aa0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31ab0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
31ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
31ae0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
31af0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
31b00 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
31b10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31b20 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
31b30 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
31b40 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
31b50 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31b60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
31b70 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
31b80 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
31b90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31ba0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31bb0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
31bc0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
31bd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31be0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31bf0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
31c00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
31c10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
31c20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31c30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31c40 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
31c50 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31c60 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31c70 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31c80 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31c90 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31ca0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31cb0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31cc0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
31cd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31ce0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31cf0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
31d00 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
31d10 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
31d20 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
31d30 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
31d40 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
31d50 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
31d60 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
31d70 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
31d80 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
31d90 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
31da0 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
31db0 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
31dc0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
31dd0 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
31de0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
31df0 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
31e00 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
31e10 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
31e20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
31e30 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
31e40 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
31e50 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
31e60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31e70 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
31e80 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
31e90 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
31ea0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
31eb0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
31ec0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31ed0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
31ee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
31ef0 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
31f00 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
31f10 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
31f20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
31f30 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
31f40 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
31f50 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
31f60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
31f70 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
31f80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31f90 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
31fa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31fb0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
31fc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31fd0 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
31fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
31ff0 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
32000 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
32010 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
32020 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
32030 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
32040 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32050 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
32060 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
32070 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
32080 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
32090 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
320a0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
320b0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
320c0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
320d0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
320e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
320f0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
32100 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
32110 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
32120 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
32130 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
32140 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
32150 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
32160 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
32170 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
32180 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
32190 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
321a0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
321b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
321c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
321d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
321e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
321f0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
32200 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
32210 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
32220 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32230 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
32240 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
32250 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
32260 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
32270 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32280 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
32290 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
322a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
322b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
322c0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
322d0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
322e0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
322f0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
32300 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
32310 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
32320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32330 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
32340 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
32350 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
32360 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
32370 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
32380 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
32390 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
323a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
323b0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
323c0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
323d0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
323e0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
323f0 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
32400 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
32410 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
32420 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
32430 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
32440 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
32450 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
32460 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
32470 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
32480 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
32490 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
324a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
324b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
324c0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
324d0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
324e0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
324f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
32500 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
32510 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32520 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
32530 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
32540 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
32550 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32560 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32570 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
32580 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
32590 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
325a0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
325b0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
325c0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
325d0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
325e0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
325f0 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
32600 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32610 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
32620 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
32630 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
32640 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32650 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
32660 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
32670 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32680 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
32690 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
326a0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
326b0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
326c0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
326d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
326e0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
326f0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32700 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
32710 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
32720 78 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65  xcept that these
32730 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
32740 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
32750 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32760 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32770 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32780 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32790 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
327a0 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
327b0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
327c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
327d0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
327e0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
327f0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32800 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
32810 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
32820 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
32830 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
32840 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
32850 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
32860 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
32870 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
32880 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
32890 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
328a0 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
328b0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
328c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
328d0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
328e0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
328f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
32900 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
32910 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
32920 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
32930 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
32940 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
32950 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
32960 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
32970 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
32980 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
32990 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
329a0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
329b0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
329c0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
329d0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
329e0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
329f0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
32a00 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
32a10 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
32a20 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
32a30 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
32a40 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
32a50 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
32a60 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
32a70 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
32a80 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
32a90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
32aa0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
32ab0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
32ac0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
32ad0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
32ae0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
32af0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
32b00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32b10 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
32b20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32b30 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
32b40 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
32b50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
32b60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
32b70 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
32b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32b90 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
32ba0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32bb0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32bc0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
32bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32be0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
32bf0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32c00 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
32c10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32c20 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
32c30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
32c40 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
32c50 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
32c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
32c70 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
32c80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
32c90 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
32ca0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32cc0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
32cd0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
32ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
32cf0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
32d00 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
32d10 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
32d20 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
32d30 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
32d40 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
32d50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
32d60 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
32d70 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
32d80 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
32d90 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
32da0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
32db0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
32dc0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
32dd0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32de0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
32df0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
32e00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
32e10 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32e20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32e30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32e40 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
32e50 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32e60 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
32e70 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
32e80 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
32e90 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
32ea0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
32eb0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
32ec0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
32ed0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
32ee0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
32ef0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
32f00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
32f10 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
32f20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
32f30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
32f40 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
32f50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32f60 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
32f70 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
32f80 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
32f90 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
32fa0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
32fb0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
32fc0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
32fd0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
32fe0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
32ff0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
33000 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
33010 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
33020 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
33030 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33040 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
33050 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33060 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33070 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
33080 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
33090 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
330a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
330b0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
330c0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
330d0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
330e0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
330f0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
33100 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
33110 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
33120 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
33130 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
33140 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
33150 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
33160 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
33170 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
33180 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
33190 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
331a0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
331b0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
331c0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
331d0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
331e0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
331f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33200 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
33210 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
33220 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
33230 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
33240 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
33250 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33260 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
33270 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
33280 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
33290 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
332a0 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
332b0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
332c0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
332d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
332e0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
332f0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
33300 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
33310 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
33320 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33330 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
33340 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
33350 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
33360 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
33370 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
33380 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
33390 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
333a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
333b0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
333c0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
333d0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
333e0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
333f0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
33400 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
33410 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
33420 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
33430 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
33440 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
33450 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
33460 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33470 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33480 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
33490 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
334a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
334b0 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
334c0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
334d0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
334e0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
334f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33500 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
33510 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
33520 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
33530 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
33540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
33550 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
33560 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
33570 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
33580 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
33590 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
335a0 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
335b0 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
335c0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
335d0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
335e0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
335f0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
33600 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
33610 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
33620 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33630 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33640 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
33650 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
33660 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33670 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
33680 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
33690 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
336a0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
336b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
336c0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
336d0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
336e0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
336f0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33700 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
33710 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
33720 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
33730 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
33740 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
33750 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33760 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33770 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33780 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33790 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
337a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
337b0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
337c0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
337d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
337e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
337f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
33800 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
33810 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
33820 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
33830 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33840 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
33850 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
33860 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
33870 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33880 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33890 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
338a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
338b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
338c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
338d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
338e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
338f0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
33900 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
33910 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33920 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
33930 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
33940 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33950 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33960 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33970 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33980 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33990 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
339a0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
339b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
339c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
339d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
339e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
339f0 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
33a00 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
33a10 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
33a20 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
33a30 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
33a40 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
33a50 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
33a60 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
33a70 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
33a80 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
33a90 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
33aa0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
33ab0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
33ac0 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
33ad0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
33ae0 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
33af0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
33b00 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
33b10 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
33b20 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
33b30 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
33b40 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
33b50 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
33b60 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
33b70 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
33b80 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
33b90 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
33ba0 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
33bb0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
33bc0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
33bd0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
33be0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
33bf0 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
33c00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33c10 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
33c20 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
33c30 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
33c40 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
33c50 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
33c60 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
33c70 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
33c80 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
33c90 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
33ca0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33cb0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
33cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33cd0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
33ce0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33cf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
33d00 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
33d10 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
33d20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33d30 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
33d40 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
33d50 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
33d60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33d70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33d80 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
33d90 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
33da0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
33db0 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
33dc0 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
33dd0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
33de0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
33df0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
33e00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
33e10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33e20 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
33e30 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
33e40 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
33e50 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
33e60 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
33e70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33e80 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
33e90 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
33ea0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
33eb0 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
33ec0 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
33ed0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
33ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33ef0 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
33f00 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
33f10 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
33f20 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
33f30 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
33f40 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
33f50 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
33f60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
33f70 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
33f80 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
33f90 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
33fa0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
33fb0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
33fc0 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
33fd0 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
33fe0 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
33ff0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
34000 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
34010 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
34020 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
34030 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
34040 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
34050 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
34060 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
34070 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
34080 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
34090 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
340a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
340b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
340c0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
340d0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
340e0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
340f0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
34100 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34110 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
34120 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
34130 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
34140 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
34150 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
34160 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34170 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
34180 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
34190 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
341a0 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
341b0 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
341c0 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
341d0 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
341e0 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
341f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34200 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
34210 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
34220 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
34230 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
34240 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
34250 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
34260 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
34270 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34280 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
34290 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
342a0 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
342b0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
342c0 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
342d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
342e0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
342f0 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
34300 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
34310 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34320 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
34330 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
34340 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
34350 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
34360 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
34370 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
34380 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
34390 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
343a0 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
343b0 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
343c0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
343d0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
343e0 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
343f0 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
34400 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
34410 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
34420 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34430 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34440 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
34450 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
34460 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34470 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
34480 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34490 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
344a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
344b0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
344c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
344d0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
344e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
344f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34500 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
34510 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
34520 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
34530 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
34540 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
34550 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
34560 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
34570 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
34580 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
34590 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
345a0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
345b0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
345c0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
345d0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
345e0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
345f0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
34600 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
34610 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
34620 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
34630 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
34640 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
34650 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
34660 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
34670 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
34680 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
34690 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
346a0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
346b0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
346c0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
346d0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
346e0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
346f0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
34700 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
34710 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
34720 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
34730 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
34740 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
34750 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
34760 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
34770 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
34780 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
34790 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
347a0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
347b0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
347c0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
347d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
347e0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
347f0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
34800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34810 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
34820 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
34830 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
34840 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
34850 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
34860 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34870 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
34880 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
34890 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
348a0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
348b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
348c0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
348d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
348e0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
348f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34900 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
34910 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
34920 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
34930 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
34940 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
34950 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
34960 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
34970 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
34980 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
34990 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
349a0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
349b0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
349c0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
349d0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
349e0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
349f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34a00 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
34a10 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34a20 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
34a30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34a40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34a50 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
34a60 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
34a70 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
34a80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34a90 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
34aa0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
34ab0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
34ac0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
34ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34ae0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
34af0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
34b00 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
34b10 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
34b20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34b30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
34b40 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
34b50 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
34b60 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
34b70 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
34b80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
34b90 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
34ba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34bb0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
34bc0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
34bd0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
34be0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
34bf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34c00 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
34c10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
34c20 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
34c30 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
34c40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
34c50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34c60 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
34c70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34c80 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
34c90 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
34ca0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
34cb0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
34cc0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
34cd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
34ce0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
34cf0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
34d00 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
34d10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34d20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
34d30 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
34d40 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
34d50 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
34d60 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
34d70 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
34d80 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
34d90 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
34da0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34db0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
34dc0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
34dd0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
34de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34df0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
34e00 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
34e10 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
34e20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
34e30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
34e40 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
34e50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34e60 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
34e70 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
34e80 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
34e90 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
34ea0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
34eb0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
34ec0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
34ed0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
34ee0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
34ef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34f00 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
34f10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34f20 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
34f30 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
34f40 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
34f50 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
34f60 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
34f70 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34f80 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
34f90 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
34fa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34fb0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
34fc0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34fd0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
34fe0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
34ff0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
35000 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
35010 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
35020 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
35030 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
35040 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
35050 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
35060 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
35070 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
35080 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
35090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
350a0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
350b0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
350c0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
350d0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
350e0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
350f0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
35100 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
35110 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
35120 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
35130 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
35140 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
35150 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35160 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
35170 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35180 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
35190 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
351a0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
351b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
351c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
351d0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
351e0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
351f0 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35200 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35210 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
35220 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
35230 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
35240 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35250 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35260 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
35270 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
35280 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35290 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
352a0 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
352b0 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
352c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
352d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
352e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
352f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
35300 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
35310 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35320 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
35330 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
35340 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
35350 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
35360 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
35370 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35380 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
35390 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
353a0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
353b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
353c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
353d0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
353e0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
353f0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
35400 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
35410 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
35420 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
35430 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
35440 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
35450 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
35460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35470 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35480 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
35490 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
354a0 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
354b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
354c0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
354d0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
354e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
354f0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
35500 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
35510 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35520 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
35530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35540 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
35550 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
35560 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
35570 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
35580 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35590 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
355a0 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
355b0 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
355c0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
355d0 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  y..** ^The sqlit
355e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
355f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35600 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35610 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c  ue of an.** appl
35620 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35630 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35640 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20   text string in 
35650 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73  an encoding.** s
35660 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
35670 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29  fifth (and last)
35680 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
35690 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a  h must be one.**
356a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
356b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
356c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
356d0 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
356e0 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51  UTF16LE]..** ^SQ
356f0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
35700 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
35710 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35720 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
35730 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
35740 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35750 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35760 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35780 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35790 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
357a0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
357b0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
357c0 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
357d0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
357e0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
357f0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35800 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
35810 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
35820 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35840 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
35850 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
35860 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
35870 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
35880 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
35890 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
358a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
358b0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
358c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
358d0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
358e0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
358f0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35900 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
35910 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
35920 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
35930 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
35940 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
35950 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
35960 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
35970 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
35980 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
35990 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
359a0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
359b0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
359c0 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
359d0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
359e0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
359f0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
35a00 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
35a10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
35a20 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
35a30 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
35a40 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
35a50 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
35a60 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
35a70 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
35a80 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
35a90 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
35aa0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35ab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35ac0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35ad0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
35ae0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
35af0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
35b00 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
35b10 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
35b20 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
35b30 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
35b40 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
35b50 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
35b60 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
35b70 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
35b80 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
35b90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35bb0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
35bc0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
35bd0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
35be0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
35bf0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
35c00 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
35c10 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
35c20 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
35c30 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
35c40 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
35c50 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
35c60 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
35c70 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
35c80 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
35c90 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
35ca0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
35cb0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
35cc0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
35cd0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
35ce0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
35cf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35d00 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
35d10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35d20 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
35d30 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
35d40 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
35d50 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
35d60 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35d70 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
35d80 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
35d90 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
35da0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
35db0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
35dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35dd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35de0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
35df0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
35e00 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35e10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35e20 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
35e30 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
35e40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35e50 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
35e60 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
35e70 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
35e80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
35e90 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
35ea0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
35eb0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
35ec0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
35ed0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
35ee0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
35ef0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
35f00 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
35f10 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
35f20 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
35f30 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
35f40 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
35f50 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
35f60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35f70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
35f80 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
35f90 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
35fa0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35fb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35fc0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
35fd0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
35fe0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
35ff0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
36000 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
36010 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
36020 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
36030 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
36040 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
36050 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
36060 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
36070 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
36080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36090 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
360a0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
360b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
360c0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
360d0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
360e0 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
360f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36110 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36120 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
36130 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36140 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34  e3_result_blob64
36150 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36160 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 73 71  *,const void*,sq
36170 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69  lite3_uint64,voi
36180 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36190 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
361a0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
361b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
361c0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
361d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
361e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
361f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36200 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36210 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
36220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36230 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36240 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36250 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
36260 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
36270 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36290 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
362a0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
362b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
362c0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
362d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
362e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
362f0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
36300 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36310 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36320 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
36330 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
36340 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
36350 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36360 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
36370 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36390 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
363a0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
363b0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
363c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
363d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
363e0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
363f0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
36400 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
36410 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
36420 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
36430 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
36440 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
36450 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  ng);.void sqlite
36460 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
36470 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36480 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36490 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
364a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
364b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
364c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
364d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
364e0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
364f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36500 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36510 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
36520 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36530 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
36540 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36550 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36560 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36570 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
36580 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36590 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
365a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
365b0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
365c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
365d0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
365e0 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
365f0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
36600 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
36610 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
36620 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
36630 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
36640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36650 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
36660 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36670 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
36680 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
36690 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
366a0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
366b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
366c0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
366d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
366e0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
366f0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
36700 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
36710 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
36720 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36730 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
36740 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
36750 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
36760 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
36770 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
36780 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
36790 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
367a0 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
367b0 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
367c0 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
367d0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
367e0 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
367f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
36800 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
36810 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
36820 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
36830 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
36840 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
36850 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
36860 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36870 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
36880 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
36890 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
368a0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
368b0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
368c0 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
368d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
368e0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
368f0 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
36900 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
36910 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
36920 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
36930 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
36940 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
36950 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
36960 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
36970 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
36980 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
36990 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
369a0 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
369b0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
369c0 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
369d0 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
369e0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
369f0 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
36a00 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
36a10 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
36a20 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
36a30 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
36a40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
36a50 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36a60 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
36a70 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
36a80 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
36a90 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
36aa0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
36ab0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
36ac0 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
36ad0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36ae0 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
36af0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
36b00 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
36b10 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
36b20 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
36b30 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
36b40 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
36b50 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
36b60 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
36b70 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
36b80 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
36b90 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
36ba0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
36bb0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
36bc0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36bd0 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
36be0 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
36bf0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
36c00 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
36c10 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
36c20 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
36c30 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
36c40 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
36c50 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36c60 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
36c70 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
36c80 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
36c90 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
36ca0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
36cb0 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
36cc0 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
36cd0 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
36ce0 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
36cf0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
36d00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36d10 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
36d20 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
36d30 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
36d40 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
36d50 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
36d60 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
36d70 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
36d80 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
36d90 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
36da0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
36db0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36dc0 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
36dd0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
36de0 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
36df0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
36e00 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
36e10 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36e20 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
36e30 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
36e40 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
36e50 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
36e60 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
36e70 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
36e80 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
36e90 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
36ea0 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
36eb0 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
36ec0 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
36ed0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
36ee0 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
36ef0 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
36f00 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
36f10 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
36f20 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
36f30 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
36f40 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
36f50 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
36f60 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
36f70 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
36f80 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
36f90 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
36fa0 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
36fb0 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
36fc0 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
36fd0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
36fe0 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
36ff0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
37000 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
37010 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
37020 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
37030 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
37040 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
37050 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37070 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37080 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
37090 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
370a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
370b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
370c0 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
370d0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
370e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
370f0 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
37100 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37110 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
37120 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
37130 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
37140 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
37150 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
37160 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
37170 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
37180 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
37190 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
371a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
371b0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
371c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
371d0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
371e0 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
371f0 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
37200 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
37210 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
37220 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37230 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
37240 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
37250 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
37260 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
37270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
37280 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
37290 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
372a0 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
372b0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
372c0 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
372d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
372e0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
372f0 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
37300 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
37310 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
37320 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
37330 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
37340 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
37350 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
37360 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
37370 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
37380 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
37390 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
373a0 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
373b0 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
373c0 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
373d0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
373e0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
373f0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37400 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
37410 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37420 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
37430 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37440 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
37450 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
37460 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
37470 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
37480 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
37490 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
374a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
374b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
374c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
374d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
374e0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
374f0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
37500 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
37510 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
37520 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
37530 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
37540 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
37550 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
37560 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
37570 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
37580 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37590 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
375a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
375b0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
375c0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
375d0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
375e0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
375f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37600 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37610 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37620 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
37630 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
37640 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
37650 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
37660 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
37670 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
37680 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
37690 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
376a0 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
376b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
376c0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
376d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
376e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
376f0 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
37700 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
37710 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
37720 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
37730 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
37740 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
37750 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
37760 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
37770 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37780 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
37790 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
377a0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
377b0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
377c0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
377d0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
377e0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
377f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37800 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
37810 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
37820 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
37830 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
37840 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37850 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
37860 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
37870 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
37880 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
37890 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
378a0 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
378b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
378c0 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
378d0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
378e0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
378f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
37900 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
37910 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37920 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
37930 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37940 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
37950 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
37960 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
37970 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
37980 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
37990 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
379a0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
379b0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
379c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
379d0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
379e0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
379f0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
37a00 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
37a10 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
37a20 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
37a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
37a40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
37a50 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
37a60 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
37a70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
37a80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
37a90 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
37aa0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
37ab0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
37ac0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37ad0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
37ae0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37af0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
37b00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37b10 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
37b20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
37b30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37b40 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37b50 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
37b60 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
37b70 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
37b80 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
37b90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37ba0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
37bb0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37bc0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
37bd0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
37be0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
37bf0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
37c00 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
37c10 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
37c20 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
37c30 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
37c40 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
37c50 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
37c60 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
37c70 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
37c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
37c90 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
37ca0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37cb0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
37cc0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
37cd0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
37ce0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
37cf0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
37d00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37d10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
37d20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
37d30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
37d40 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
37d50 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
37d60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f  int sqlite3_key_
37d70 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
37d80 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
37d90 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
37da0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
37db0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
37dc0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
37dd0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
37de0 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  e database */.  
37df0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
37e00 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
37e10 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
37e20 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
37e30 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
37e40 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
37e50 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
37e60 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
37e70 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
37e80 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
37e90 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
37ea0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
37eb0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
37ec0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
37ed0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
37ee0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
37ef0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
37f00 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
37f10 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
37f20 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
37f30 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
37f40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37f60 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37f70 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37f80 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37f90 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37fa0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
37fb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
37fc0 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
37fd0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
37fe0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
37ff0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
38000 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
38010 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
38020 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
38030 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
38040 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
38050 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38060 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
38070 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
38080 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
38090 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
380a0 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
380b0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
380c0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
380d0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
380e0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
380f0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
38100 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68  _see(.  const ch
38110 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
38120 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
38130 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
38140 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66  ;.#endif..#ifdef
38150 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43   SQLITE_ENABLE_C
38160 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  EROD./*.** Speci
38170 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
38180 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f  n key for a CERO
38190 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  D database.  Unl
381a0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
381b0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43  d, none of the C
381c0 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69  EROD routines wi
381d0 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
381e0 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
381f0 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74  e_cerod(.  const
38200 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61   char *zPassPhra
38210 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74  se        /* Act
38220 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a  ivation phrase *
38230 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  /.);.#endif../*.
38240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
38250 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
38260 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
38270 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
38280 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
38290 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
382a0 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
382b0 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
382c0 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
382d0 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
382e0 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
382f0 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
38300 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
38310 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
38320 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75  stem does not su
38330 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75  pport sleep requ
38340 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c  ests with.** mil
38350 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65  lisecond time re
38360 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74  solution, then t
38370 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20  he time will be 
38380 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a  rounded up to.**
38390 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63   the nearest sec
383a0 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20  ond. The number 
383b0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
383c0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
383d0 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
383e0 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
383f0 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
38400 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
38410 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
38420 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
38430 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
38440 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
38450 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
38460 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
38470 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c  ect.  If the xSl
38480 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20  eep() method.** 
38490 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  of the default V
384a0 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  FS is not implem
384b0 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c  ented correctly,
384c0 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   or not implemen
384d0 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74  ted at.** all, t
384e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
384f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65   of sqlite3_slee
38500 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20  p() may deviate 
38510 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70  from the descrip
38520 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70  tion.** in the p
38530 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
38540 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  hs..*/.int sqlit
38550 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
38560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38570 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
38580 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
38590 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
385a0 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
385b0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
385c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
385d0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
385e0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
385f0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
38600 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
38610 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
38620 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
38630 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
38640 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
38650 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
38660 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
38670 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
38680 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
38690 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
386a0 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
386b0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
386c0 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
386d0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
386e0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
386f0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
38700 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
38710 74 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e 67  tions are strong
38720 6c 79 20 64 69 73 63 6f 75 72 61 67 65 64 20 66  ly discouraged f
38730 72 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20 67  rom using this g
38740 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a  lobal variable..
38750 2a 2a 20 49 74 20 69 73 20 72 65 71 75 69 72 65  ** It is require
38760 64 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70 6f  d to set a tempo
38770 72 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57  rary folder on W
38780 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 28  indows Runtime (
38790 57 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66  WinRT)..** But f
387a0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61  or all other pla
387b0 74 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68 69  tforms, it is hi
387c0 67 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64  ghly recommended
387d0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
387e0 6e 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72 65  ns.** neither re
387f0 61 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68 69  ad nor write thi
38800 73 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68 69  s variable.  Thi
38810 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
38820 65 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a 20  e is a relic.** 
388