/ Hex Artifact Content
Login

Artifact 821027573c481e45ba276b078a3ae9ebaeb9bb92:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 73  delete opertions
86e0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
86f0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8700: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8710: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8720: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8730: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8740: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8750: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8760: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8770: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8780: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8790: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
87a0: 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73 20  those to values 
87b0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
87c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
87d0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
87e0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
87f0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
8800: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
8810: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8820: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
8830: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
8840: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
8850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
8860: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
8870: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
8880: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
8890: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
88a0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
88b0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
88c0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
88d0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
88e0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
88f0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
8900: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8910: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
8920: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
8930: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
8940: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
8950: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
8960: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
8970: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
8980: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
8990: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
89a0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
89b0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
89c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
89d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
89e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
89f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
8a00: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
8a10: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
8a20: 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73 65  te AHead Log] se
8a30: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
8a40: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
8a50: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
8a60: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
8a70: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
8a80: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
8a90: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
8aa0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
8ab0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
8ac0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
8ad0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
8ae0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
8af0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
8b00: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
8b10: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
8b20: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
8b30: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
8b40: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
8b50: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
8b60: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
8b70: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
8b80: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
8b90: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
8ba0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8bc0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
8bd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8be0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
8bf0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
8c00: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
8c10: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
8c20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
8c30: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
8c40: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
8c50: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
8c60: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c70: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
8c80: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
8c90: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
8ca0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
8cb0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
8cc0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
8cd0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
8ce0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
8cf0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
8d00: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
8d10: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
8d20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
8d30: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
8d40: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
8d50: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
8d60: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8d70: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
8d80: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
8d90: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
8da0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
8db0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
8dc0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
8dd0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
8de0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
8df0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
8e00: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
8e10: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
8e20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
8e30: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
8e40: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
8e50: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
8e60: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
8e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8e80: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8e90: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
8ea0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
8eb0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8ec0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
8ed0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
8ee0: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
8ef0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
8f00: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
8f10: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
8f20: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8f30: 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69  T        5.#defi
8f40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8f50: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
8f60: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
8f70: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8f80: 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69  NTER     7.#defi
8f90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8fa0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
8fb0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
8fd0: 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69  _RETRY   9.#defi
8fe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8ff0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
9000: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
9010: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
9020: 45 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a  E       11../*.*
9030: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
9040: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
9050: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
9060: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
9070: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
9080: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
9090: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
90a0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
90b0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
90c0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
90d0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
90e0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
90f0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
9100: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
9110: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
9120: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
9130: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
9140: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
9150: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
9160: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
9170: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
9180: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
9190: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
91a0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
91b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
91c0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
91d0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
91e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
91f0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
9200: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
9210: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
9220: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
9230: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
9240: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
9250: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
9260: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
9270: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
9280: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
9290: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
92a0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
92b0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
92c0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
92d0: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
92e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
92f0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
9300: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
9310: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
9320: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
9330: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
9340: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
9350: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
9360: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
9370: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
9380: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
9390: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
93a0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
93b0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
93c0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
93d0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
93e0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
93f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
9400: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
9410: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
9420: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
9430: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
9440: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
9450: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
9460: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
9470: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
9480: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
9490: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
94a0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
94b0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
94c0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
94d0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
94e0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
94f0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
9500: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
9510: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
9520: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
9530: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
9540: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
9550: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
9560: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
9570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
9580: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
9590: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
95a0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
95b0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
95c0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
95d0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
95e0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
95f0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
9600: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
9610: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
9620: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
9630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
9640: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
9650: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
9660: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
9670: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
9680: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
9690: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
96a0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
96b0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
96c0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
96d0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
96e0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
96f0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
9700: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
9710: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
9720: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9730: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
9740: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
9750: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
9760: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
9770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
9780: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
9790: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
97a0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
97b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
97c0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
97d0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
97e0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
97f0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
9800: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
9810: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
9820: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
9830: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
9840: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
9850: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
9860: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
9870: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
9880: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
9890: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
98a0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
98b0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
98c0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
98d0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
98e0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
98f0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
9900: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
9910: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
9920: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
9930: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70  e than.** 10 alp
9940: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
9950: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
9960: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
9970: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
9980: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
9990: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
99a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
99b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
99c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
99d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
99e0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
99f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9a00: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
9a10: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
9a20: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
9a30: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
9a40: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
9a50: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
9a60: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
9a70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
9a80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
9a90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
9aa0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
9ab0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
9ac0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
9ad0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
9ae0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
9af0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
9b00: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
9b10: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
9b20: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
9b30: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
9b40: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
9b50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9b60: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
9b70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
9b80: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
9b90: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
9ba0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
9bb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
9bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
9bd0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
9be0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9bf0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
9c00: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
9c10: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
9c20: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
9c30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
9c40: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
9c50: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
9c60: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
9c70: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
9c80: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
9c90: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
9ca0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
9cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
9cc0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
9cd0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
9ce0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
9cf0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
9d00: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
9d10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
9d20: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
9d30: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
9d40: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
9d50: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
9d60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9d70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9d80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
9d90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9da0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
9db0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9dc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
9dd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9de0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
9df0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9e00: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
9e10: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
9e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
9e30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9e40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
9e50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
9e60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9e70: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
9e80: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
9e90: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
9ea0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
9eb0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
9ec0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
9ed0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
9ee0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
9ef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
9f00: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
9f10: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
9f20: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
9f30: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
9f40: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
9f50: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
9f60: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
9f70: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
9f80: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
9f90: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
9fa0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
9fb0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
9fc0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
9fd0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
9fe0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
9ff0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
a000: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
a010: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
a020: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
a030: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
a040: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
a050: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
a060: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
a070: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
a080: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
a090: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
a0a0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
a0b0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
a0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
a0d0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
a0e0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
a0f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a100: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a110: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
a120: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
a130: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
a140: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
a150: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
a160: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
a170: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
a180: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
a190: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
a1a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
a1b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
a1c0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
a1d0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
a1e0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
a1f0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
a200: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
a210: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
a220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
a230: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
a240: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
a250: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
a260: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
a270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
a280: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
a290: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
a2a0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
a2b0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
a2c0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
a2d0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
a2e0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
a2f0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
a300: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
a310: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
a320: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
a330: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
a340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
a350: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
a360: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
a370: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
a380: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
a390: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
a3a0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
a3b0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
a3c0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
a3d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
a3e0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
a3f0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
a400: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
a410: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
a420: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
a430: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
a440: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
a450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
a460: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
a470: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
a480: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
a490: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
a4a0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
a4b0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
a4c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
a4d0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
a4e0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
a4f0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
a500: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
a510: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
a520: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
a530: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
a540: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
a550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
a560: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
a570: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
a580: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
a590: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
a5a0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
a5b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
a5c0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
a5d0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
a5e0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
a5f0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
a600: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
a610: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
a620: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
a630: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
a640: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
a650: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
a660: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
a670: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
a680: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
a690: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
a6a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
a6b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
a6c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
a6d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
a6e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
a6f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
a700: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
a710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
a720: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
a730: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
a740: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
a750: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
a760: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
a770: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
a780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
a790: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
a7a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
a7b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
a7c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
a7d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
a7e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
a7f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
a800: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
a810: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
a820: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
a830: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
a840: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
a850: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
a860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
a870: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
a880: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
a890: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
a8a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
a8b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
a8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
a8d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
a8e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
a8f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
a900: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
a910: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
a920: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
a930: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
a940: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
a950: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
a960: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
a970: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
a980: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
a990: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
a9a0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
a9b0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
a9c0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
a9d0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
a9e0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
a9f0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
aa00: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
aa10: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
aa20: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
aa30: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
aa40: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
aa50: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
aa60: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
aa70: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
aa80: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
aa90: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
aaa0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
aab0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
aac0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
aad0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
aae0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
aaf0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
ab00: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
ab10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
ab20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
ab30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
ab40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
ab50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
ab60: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
ab70: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
ab80: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
ab90: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
aba0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
abb0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
abc0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
abd0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
abe0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
abf0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
ac00: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
ac10: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
ac20: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
ac30: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
ac40: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
ac50: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
ac60: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
ac70: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
ac80: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
ac90: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
aca0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
acb0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
acc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
acd0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
ace0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
acf0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
ad00: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
ad10: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
ad20: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
ad30: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
ad40: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
ad50: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
ad60: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
ad70: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
ad80: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
ad90: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
ada0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
adb0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
adc0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
add0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
ade0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
adf0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
ae00: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
ae10: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
ae20: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
ae30: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
ae40: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
ae50: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
ae60: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
ae70: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
ae80: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
ae90: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
aea0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
aeb0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
aec0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
aed0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
aee0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
aef0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
af00: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
af10: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
af20: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
af30: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
af40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
af50: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
af60: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
af70: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
af80: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
af90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
afa0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
afb0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
afc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
afd0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
afe0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
aff0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
b000: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
b010: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
b020: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
b030: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
b040: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
b050: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
b060: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
b070: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
b080: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
b090: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
b0a0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
b0b0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
b0c0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
b0d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
b0e0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
b0f0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
b100: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
b110: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
b120: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
b130: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
b140: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
b150: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
b160: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
b170: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
b180: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
b190: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
b1a0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
b1b0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
b1c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
b1d0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
b1e0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
b1f0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
b200: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
b210: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
b220: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
b230: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
b240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
b250: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
b260: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b270: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
b280: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
b290: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
b2a0: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
b2b0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
b2c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b2d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
b2e0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
b2f0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
b300: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b310: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
b320: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
b330: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
b340: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
b350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
b360: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
b370: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
b380: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
b390: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
b3a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b3b0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
b3c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
b3d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
b3e0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
b3f0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
b400: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
b410: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
b420: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
b430: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
b440: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
b450: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
b460: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
b470: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
b480: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
b490: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
b4a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
b4b0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
b4c0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
b4d0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
b4e0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
b4f0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
b500: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
b510: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
b520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
b530: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
b540: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b550: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b560: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
b570: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
b580: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
b590: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
b5a0: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
b5b0: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
b5c0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
b5d0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
b5e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b5f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
b600: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
b610: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b620: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
b630: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
b640: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
b650: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
b660: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
b670: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
b680: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
b690: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
b6a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b6b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
b6c0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
b6d0: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
b6e0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
b6f0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
b700: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b710: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
b720: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
b730: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
b740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b750: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
b760: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
b770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b780: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
b790: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
b7a0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
b7b0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
b7c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b7d0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
b7e0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
b7f0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
b800: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
b810: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
b820: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
b830: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
b840: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
b850: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
b860: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
b870: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
b880: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
b890: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
b8a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
b8b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
b8c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
b8d0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
b8e0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
b8f0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
b900: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
b910: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
b920: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
b930: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
b940: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
b950: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
b960: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
b970: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
b980: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
b990: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
b9a0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
b9b0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
b9c0: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
b9d0: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
b9e0: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
b9f0: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
ba00: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
ba10: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
ba20: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
ba30: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
ba40: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
ba50: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
ba60: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ba70: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
ba80: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
ba90: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
baa0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
bab0: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
bac0: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
bad0: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
bae0: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
baf0: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
bb00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
bb10: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
bb20: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
bb30: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
bb40: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
bb50: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
bb60: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
bb70: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
bb80: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
bb90: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
bba0: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
bbb0: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
bbc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bbd0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
bbe0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
bbf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
bc00: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
bc10: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
bc20: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
bc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bc40: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
bc50: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
bc60: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
bc70: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
bc80: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
bc90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
bca0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
bcb0: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
bcc0: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
bcd0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
bce0: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
bcf0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
bd00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
bd10: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
bd20: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
bd30: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
bd40: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
bd50: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
bd60: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
bd70: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
bd80: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
bd90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
bda0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
bdb0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
bdc0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
bdd0: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
bde0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
bdf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
be00: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
be10: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
be20: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
be30: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
be40: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
be50: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
be60: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
be70: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
be80: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
be90: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72  given no the cor
bea0: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
beb0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
bec0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
bed0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
bee0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
bef0: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
bf00: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
bf10: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
bf20: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
bf30: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
bf40: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
bf50: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
bf60: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
bf70: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
bf80: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
bf90: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
bfb0: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
bfc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
bfd0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
bfe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bff0: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
c000: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
c010: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
c020: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
c030: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
c040: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
c050: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
c060: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
c070: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
c080: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
c090: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
c0a0: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
c0b0: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
c0c0: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
c0d0: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
c0e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
c0f0: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
c100: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
c110: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
c120: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
c130: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
c140: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c150: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
c160: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
c170: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
c180: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
c190: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
c1a0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
c1b0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
c1c0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
c1d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
c1e0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
c1f0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
c200: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
c210: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
c220: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
c230: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
c240: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
c250: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
c260: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
c270: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
c280: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
c290: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
c2a0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
c2b0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
c2c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
c2d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
c2e0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
c2f0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
c300: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
c310: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c320: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
c330: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
c340: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
c350: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
c360: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
c370: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c380: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
c390: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
c3a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
c3b0: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
c3c0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
c3d0: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
c3e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
c3f0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
c400: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
c410: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
c420: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
c430: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
c440: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c450: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
c460: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
c470: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
c480: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c490: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
c4a0: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
c4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
c4c0: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
c4d0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
c4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c4f0: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
c500: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
c510: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
c520: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
c530: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
c540: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
c550: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
c560: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c570: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
c580: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
c590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c5a0: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
c5b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
c5c0: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
c5d0: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
c5e0: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
c5f0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
c600: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
c610: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
c620: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
c630: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
c640: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
c650: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
c660: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
c670: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
c680: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
c690: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
c6a0: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
c6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
c6c0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
c6d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
c6e0: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
c6f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
c700: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
c710: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
c720: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
c730: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c740: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
c750: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
c760: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
c770: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
c780: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c790: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
c7a0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
c7b0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
c7c0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
c7d0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
c7e0: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
c7f0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
c800: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
c810: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
c820: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
c830: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
c840: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c850: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
c860: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
c870: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
c880: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
c890: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
c8a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
c8b0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
c8c0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
c8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c8e0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
c8f0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
c900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c910: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
c920: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
c930: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
c940: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
c950: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
c960: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
c970: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
c980: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
c990: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
c9a0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
c9b0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
c9c0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
c9d0: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
c9e0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
c9f0: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
ca00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
ca10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
ca20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
ca30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
ca40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
ca50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
ca60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
ca70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ca80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
ca90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
caa0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
cab0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
cac0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
cad0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
cae0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
caf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
cb00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
cb10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
cb20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
cb30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
cb40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
cb50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
cb60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
cb70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
cb80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
cb90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
cba0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
cbb0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
cbc0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
cbd0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
cbe0: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
cbf0: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
cc00: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
cc10: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
cc20: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
cc30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cc40: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
cc50: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
cc60: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
cc70: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
cc80: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
cc90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
cca0: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
ccb0: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
ccc0: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
ccd0: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
cce0: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
ccf0: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
cd00: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
cd10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
cd20: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
cd30: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
cd40: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
cd50: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
cd60: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
cd70: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
cd80: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
cd90: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
cda0: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
cdb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
cdc0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
cdd0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
cde0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
cdf0: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
ce00: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
ce10: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
ce20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ce30: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
ce40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
ce50: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
ce60: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
ce70: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
ce80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
ce90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
cea0: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
ceb0: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
cec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
ced0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cee0: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
cef0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
cf00: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
cf10: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
cf20: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
cf30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
cf40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
cf50: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
cf60: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
cf70: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
cf80: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
cf90: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
cfa0: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
cfb0: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
cfc0: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
cfd0: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
cfe0: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
cff0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
d000: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
d010: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
d020: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d030: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
d040: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
d050: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
d060: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
d070: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
d080: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
d090: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
d0a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
d0b0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
d0c0: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
d0d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
d0e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
d0f0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
d100: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
d110: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
d120: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
d130: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
d140: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
d150: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d160: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
d170: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
d180: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
d190: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
d1a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
d1b0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
d1c0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
d1d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
d1e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
d1f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
d200: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
d210: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
d220: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
d230: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
d240: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
d250: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
d260: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
d270: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
d280: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
d290: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
d2a0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
d2b0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
d2c0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
d2d0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
d2e0: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
d2f0: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
d300: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
d310: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
d320: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
d330: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d340: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
d350: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
d360: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
d370: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
d380: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
d390: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
d3a0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
d3b0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
d3c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
d3d0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
d3e0: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
d3f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
d400: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
d410: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
d420: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
d430: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
d440: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
d450: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
d460: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
d470: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d480: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
d490: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
d4a0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
d4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
d4c0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
d4d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d4e0: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
d4f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
d500: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
d510: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
d520: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d530: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
d540: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
d550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
d560: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
d570: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
d580: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
d590: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
d5a0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
d5b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
d5c0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
d5d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d5e0: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
d5f0: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
d600: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
d610: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
d620: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
d630: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
d640: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
d650: 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
d660: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
d670: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d680: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
d690: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d6a0: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
d6b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
d6c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
d6d0: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
d6e0: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
d6f0: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
d700: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
d710: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
d720: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
d730: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
d740: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
d750: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
d760: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
d770: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d780: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
d790: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
d7a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d7b0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
d7c0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
d7d0: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
d7e0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
d7f0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
d800: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
d810: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
d820: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
d830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
d840: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
d850: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
d860: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
d870: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d880: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
d890: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d8a0: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
d8b0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d8c0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
d8d0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
d8e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
d8f0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
d900: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
d910: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
d920: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
d930: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
d940: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
d950: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d960: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
d970: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
d980: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
d990: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
d9a0: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
d9b0: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
d9c0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
d9d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
d9e0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
d9f0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
da00: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
da10: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
da20: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
da30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
da40: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
da50: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
da60: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
da70: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
da80: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
da90: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
daa0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
dab0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
dac0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
dad0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
dae0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
daf0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
db00: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
db10: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
db20: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
db30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
db40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
db50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
db60: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
db70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
db80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
db90: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
dba0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
dbb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
dbc0: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
dbd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
dbe0: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
dbf0: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
dc00: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
dc10: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
dc20: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
dc30: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
dc40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
dc50: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
dc60: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
dc70: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
dc80: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
dc90: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
dca0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
dcb0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
dcc0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
dcd0: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
dce0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
dcf0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
dd00: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
dd10: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
dd20: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
dd30: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
dd40: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
dd50: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
dd60: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
dd70: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
dd80: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
dd90: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
dda0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
ddb0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
ddc0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
ddd0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
dde0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ddf0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
de00: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
de10: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
de20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
de30: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
de40: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
de50: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
de60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
de70: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
de80: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
de90: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
dea0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
deb0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
dec0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
ded0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
dee0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
def0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
df00: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
df10: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
df20: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
df30: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
df40: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
df50: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
df60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
df70: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
df80: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
df90: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
dfa0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
dfb0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
dfc0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
dfd0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
dfe0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
dff0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
e000: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
e010: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
e020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e030: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
e040: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
e050: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
e060: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
e070: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
e080: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
e090: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
e0a0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
e0b0: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
e0c0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
e0d0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
e0e0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
e0f0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
e100: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
e110: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
e120: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
e130: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
e140: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
e150: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
e160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e170: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
e180: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
e190: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
e1a0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
e1b0: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
e1c0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
e1d0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
e1e0: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
e1f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
e200: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
e210: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
e220: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
e230: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
e240: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
e250: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
e260: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
e270: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
e280: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
e290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e2a0: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
e2b0: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
e2c0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
e2d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e2e0: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
e2f0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
e300: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
e310: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
e320: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
e330: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
e340: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
e350: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
e360: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
e370: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
e380: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
e390: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
e3a0: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
e3b0: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
e3c0: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
e3d0: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
e3e0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
e3f0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
e400: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
e410: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
e420: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
e430: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
e440: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
e450: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
e460: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
e470: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
e480: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
e490: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
e4a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
e4b0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
e4c0: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
e4d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e4e0: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
e4f0: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
e500: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
e510: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
e520: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
e530: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
e540: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
e550: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
e560: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
e570: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
e580: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
e590: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e5a0: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
e5b0: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
e5c0: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
e5d0: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
e5e0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
e5f0: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
e600: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
e610: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
e620: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
e630: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
e640: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
e650: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
e660: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
e670: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
e680: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
e690: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
e6a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
e6b0: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
e6c0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
e6d0: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
e6e0: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
e6f0: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
e700: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e710: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
e720: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
e730: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
e740: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
e750: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
e760: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
e770: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
e780: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
e790: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
e7a0: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
e7b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
e7c0: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
e7d0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
e7e0: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
e7f0: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
e800: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
e810: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
e820: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
e830: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
e840: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
e850: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
e860: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
e870: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
e880: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
e890: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
e8a0: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
e8b0: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
e8c0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
e8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
e8e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
e8f0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
e900: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
e910: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
e920: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
e930: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
e940: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e950: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
e960: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
e970: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
e980: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
e990: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e9a0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
e9b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
e9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e9d0: 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
e9e0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
e9f0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
ea00: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
ea10: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
ea20: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
ea30: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
ea40: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
ea50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ea60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
ea70: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
ea80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
ea90: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
eaa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
eab0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
eac0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
ead0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
eae0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
eaf0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
eb00: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
eb10: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
eb20: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
eb30: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
eb40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
eb50: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
eb60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
eb70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
eb80: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
eba0: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
ebb0: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
ebc0: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
ebd0: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
ebe0: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
ebf0: 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
ec00: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
ec10: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
ec20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ec30: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ec40: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ec50: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ec60: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
ec70: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
ec80: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
ec90: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
eca0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
ecb0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ecc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
ecd0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
ece0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
ecf0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
ed00: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
ed10: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
ed20: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
ed30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
ed40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
ed50: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
ed60: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
ed70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
ed80: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
ed90: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
eda0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
edb0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
edc0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
edd0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
ede0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
edf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ee00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
ee10: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
ee20: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
ee30: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
ee40: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
ee50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ee60: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
ee70: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
ee80: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
ee90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
eea0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
eeb0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
eec0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
eed0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
eee0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
eef0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
ef00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
ef10: 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
ef20: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
ef30: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
ef40: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
ef50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
ef60: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ef70: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
ef80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
ef90: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
efa0: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
efb0: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
efc0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
efd0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
efe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
eff0: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
f000: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
f010: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
f020: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
f030: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
f040: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
f050: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
f060: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
f070: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
f080: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
f090: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f0a0: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
f0b0: 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
f0c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f0d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f0e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f0f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f100: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f110: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f120: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
f130: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
f140: 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
f150: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
f160: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f170: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
f180: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
f190: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
f1a0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
f1b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f1c0: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
f1d0: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
f1e0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
f1f0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
f200: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f210: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
f220: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
f230: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
f240: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
f250: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
f260: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
f270: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
f280: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
f290: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
f2a0: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
f2b0: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
f2c0: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
f2d0: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
f2e0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
f2f0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
f300: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
f310: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
f320: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
f330: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
f340: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f350: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f360: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
f370: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
f380: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
f390: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
f3a0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
f3b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f3c0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
f3d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
f3e0: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
f3f0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
f400: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
f410: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
f420: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
f430: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
f440: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
f450: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
f460: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
f470: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
f480: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f490: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
f4a0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
f4b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
f4c0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
f4d0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
f4e0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
f4f0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
f500: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
f510: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
f520: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f530: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
f540: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
f550: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
f560: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
f570: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
f580: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f590: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
f5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f5b0: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
f5c0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
f5d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f5e0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f5f0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f600: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f610: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f620: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f630: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
f640: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f650: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
f660: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
f670: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
f680: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f690: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
f6a0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
f6b0: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
f6c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
f6d0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
f6e0: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
f6f0: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
f700: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
f710: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
f720: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f730: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f740: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
f750: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
f760: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
f770: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
f780: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
f790: 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
f7a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f7b0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
f7c0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f7d0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f7e0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f7f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f800: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
f810: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f820: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
f830: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
f840: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f850: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
f860: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
f870: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
f880: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
f890: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
f8a0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
f8b0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
f8c0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
f8d0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
f8e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
f8f0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
f900: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
f910: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
f920: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
f930: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
f940: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
f950: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
f960: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
f970: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
f980: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f990: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
f9a0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
f9b0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
f9c0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
f9d0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
f9e0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
f9f0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
fa00: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
fa10: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
fa20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fa30: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
fa40: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
fa50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
fa60: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
fa70: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
fa80: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
fa90: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
faa0: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
fab0: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
fac0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
fad0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
fae0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
faf0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
fb00: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fb10: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
fb20: 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
fb30: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
fb40: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
fb50: 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
fb60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
fb70: 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
fb80: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
fb90: 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
fba0: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
fbb0: 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
fbc0: 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
fbd0: 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
fbe0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
fbf0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
fc00: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
fc10: 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
fc20: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fc30: 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
fc40: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
fc50: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
fc60: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
fc70: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
fc80: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
fc90: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
fca0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
fcb0: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
fcc0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
fcd0: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
fce0: 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
fcf0: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
fd00: 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
fd10: 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
fd20: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
fd30: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
fd40: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
fd50: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
fd60: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
fd70: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
fd80: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
fd90: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
fda0: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
fdb0: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
fdc0: 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
fdd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fde0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
fdf0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
fe00: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
fe10: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
fe20: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
fe30: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
fe40: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
fe50: 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
fe60: 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
fe70: 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
fe80: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
fe90: 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
fea0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
feb0: 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
fec0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
fed0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
fee0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
fef0: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
ff00: 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
ff10: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
ff20: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
ff30: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
ff40: 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
ff50: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
ff60: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
ff70: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
ff80: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
ff90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ffa0: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
ffb0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
ffc0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
ffd0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
ffe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
fff0: 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
10000 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
10010 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
10020 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
10030 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
10040 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
10050 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
10060 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
10070 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
10080 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
10090 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
100a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
100b0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
100c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
100d0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
100e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
100f0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
10100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
10110 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10130 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
10140 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10150 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10160 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
10170 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
10180 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
10190 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
101a0 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
101b0 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
101c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
101d0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
101e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
101f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
10200 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
10210 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
10220 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
10230 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
10240 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
10250 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
10260 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
10270 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
10280 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
10290 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
102a0 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
102b0 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
102c0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
102d0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
102e0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
102f0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
10300 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
10310 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
10320 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
10330 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
10340 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
10350 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
10360 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
10370 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
10380 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
10390 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
103a0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
103b0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
103c0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
103d0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
103e0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
103f0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
10400 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
10410 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
10420 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
10430 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
10440 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
10450 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
10460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10470 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
10480 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
10490 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
104a0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
104b0 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
104c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
104d0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
104e0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
104f0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
10500 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
10510 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
10520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10530 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
10540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
10550 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10560 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
10570 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10580 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10590 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
105a0 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
105b0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
105c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
105d0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
105e0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
105f0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
10600 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
10610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10620 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
10630 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10640 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
10650 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
10660 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
10670 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
10680 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
10690 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
106a0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
106b0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
106c0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
106d0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
106e0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
106f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
10700 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
10710 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
10720 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10730 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
10740 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
10750 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
10760 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
10770 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
10780 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10790 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
107a0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
107b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
107c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
107d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
107e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
107f0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
10800 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
10810 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
10820 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10830 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
10840 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
10850 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
10860 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
10870 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
10880 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
10890 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
108a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
108b0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
108c0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
108d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
108e0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
108f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
10900 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10910 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
10920 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62  t 2^12. Reasonab
10930 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
10940 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
10950 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
10960 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38   2^5 through 2^8
10970 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10980 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
10990 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
109a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
109b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
109c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
109d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
109e0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
109f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
10a00 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
10a10 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10a20 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
10a30 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
10a40 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
10a50 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
10a60 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
10a70 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
10a80 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
10a90 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
10aa0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
10ab0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
10ac0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
10ad0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
10ae0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
10af0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
10b00 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
10b10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10b20 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
10b30 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
10b40 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
10b50 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10b60 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10b70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10b80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10b90 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
10ba0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
10bb0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
10bc0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
10bd0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
10be0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
10bf0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
10c00 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
10c10 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
10c20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
10c30 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
10c40 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
10c50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10c60 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
10c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10c80 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
10c90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
10ca0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
10cb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10cc0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
10cd0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
10ce0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
10cf0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10d00 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
10d10 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
10d20 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
10d30 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
10d40 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
10d50 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
10d60 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
10d70 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
10d80 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
10d90 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
10da0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
10db0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
10dc0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
10dd0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
10de0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
10df0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
10e00 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
10e10 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
10e20 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
10e30 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10e40 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10e50 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10e60 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10e70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10e80 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
10e90 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
10ea0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
10eb0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
10ec0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
10ed0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
10ee0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10ef0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
10f00 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
10f10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f20 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
10f30 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
10f40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
10f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10f60 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
10f70 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
10f80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
10f90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10fa0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
10fb0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
10fc0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
10fd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10fe0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
10ff0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
11000 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
11010 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11020 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
11030 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
11040 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
11050 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
11060 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
11070 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
11080 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
11090 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
110a0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
110b0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
110c0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
110d0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
110e0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
110f0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
11100 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11110 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
11120 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11130 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
11140 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
11150 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
11160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
11170 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
11180 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
11190 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
111a0 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64  NFIG_PCACHE]] <d
111b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
111c0 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
111d0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
111e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
111f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11200 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
11210 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
11220 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
11230 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
11240 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
11250 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
11260 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
11270 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11280 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
11290 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
112a0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
112b0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
112c0 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
112d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
112e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
112f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
11300 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
11310 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
11320 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11330 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11340 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11350 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11370 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
11380 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
11390 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
113a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
113b0 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
113c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
113d0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
113e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
113f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
11400 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11410 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
11420 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
11430 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
11440 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11450 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
11460 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
11470 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
11480 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
11490 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
114a0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
114b0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
114c0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
114d0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
114e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
114f0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
11500 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
11510 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
11520 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
11530 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
11540 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
11550 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
11560 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
11570 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
11580 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
11590 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
115a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
115b0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
115c0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
115d0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
115e0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
115f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
11600 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11610 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
11620 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
11630 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
11640 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
11650 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
11660 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
11670 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
11680 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
11690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
116a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
116b0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
116c0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
116d0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
116e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
116f0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
11700 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
11710 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
11720 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
11730 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
11740 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
11750 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
11760 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
11770 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
11780 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
11790 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
117a0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
117b0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
117c0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
117d0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
117e0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
117f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
11800 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
11810 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
11820 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
11830 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
11840 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
11850 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11860 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
11870 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11880 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
11890 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
118a0 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
118b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
118c0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
118d0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
118e0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
118f0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
11900 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
11910 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
11920 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
11930 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
11940 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
11950 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67   If URI handling
11960 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
11970 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
11980 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
11990 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
119a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
119b0 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
119c0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
119d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
119e0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
119f0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
11a00 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
11a10 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
11a20 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
11a30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
11a40 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
11a50 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
11a60 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
11a70 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66  on is opened. If
11a80 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
11a90 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
11aa0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
11ab0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
11ac0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
11ad0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
11ae0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
11af0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
11b00 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
11b10 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  . By default, UR
11b20 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
11b30 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
11b40 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
11b50 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
11b60 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
11b70 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
11b80 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
11b90 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
11ba0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
11bb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11bc0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
11bd0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
11be0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11bf0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
11c00 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
11c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11c20 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
11c30 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
11c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11c50 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
11c60 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
11c70 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
11c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11c90 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
11ca0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
11cb0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
11cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11cd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
11ce0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
11cf0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
11d00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11d10 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
11d20 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
11d30 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
11d40 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
11d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
11d60 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
11d70 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
11d80 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
11d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11da0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
11db0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
11dc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11dd0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
11de0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
11df0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
11e00 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
11e10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11e20 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
11e30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11e40 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
11e50 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
11e60 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
11e70 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
11e80 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
11e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
11ea0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
11eb0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
11ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11ed0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
11ee0 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69       14  /* sqli
11ef0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
11f00 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
11f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11f20 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
11f30 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
11f40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
11f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11f60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
11f70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
11f80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
11f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
11fa0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
11fb0 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  int */../*.** CA
11fc0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
11fd0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
11fe0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
11ff0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
12000 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
12010 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
12020 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
12030 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
12040 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
12050 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12060 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
12070 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12080 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
12090 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
120a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
120b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
120c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
120d0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
120e0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
120f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
12100 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
12110 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
12120 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
12130 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
12140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
12150 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
12160 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
12170 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
12180 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
12190 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
121a0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
121b0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
121c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
121d0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
121e0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
121f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12200 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
12210 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
12220 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
12230 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
12240 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12250 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
12260 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
12270 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
12280 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
12290 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
122a0 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
122b0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
122c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
122d0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
122e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122f0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
12300 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
12310 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
12320 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
12330 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
12340 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
12350 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
12360 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
12370 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
12380 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12390 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
123a0 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
123b0 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
123c0 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
123d0 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
123e0 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
123f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
12400 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
12410 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
12420 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
12430 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
12440 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
12450 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
12460 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
12470 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
12480 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
12490 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
124a0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
124b0 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
124c0 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
124d0 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
124e0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
124f0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
12500 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
12510 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
12520 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
12530 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
12540 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
12550 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
12560 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
12570 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
12580 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
12590 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
125a0 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
125b0 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
125c0 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
125d0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
125e0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
125f0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
12600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
12610 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
12620 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
12630 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
12640 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
12650 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
12660 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
12670 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
12680 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
12690 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
126a0 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
126b0 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
126c0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
126d0 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
126e0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
126f0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
12700 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
12710 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
12720 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
12730 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
12740 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
12750 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
12760 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
12770 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
12780 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
12790 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
127a0 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
127b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
127c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
127d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
127e0 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
127f0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
12800 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
12810 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
12820 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
12830 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
12840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12850 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
12860 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
12870 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
12880 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
12890 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
128a0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
128b0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
128c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
128d0 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
128e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
128f0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
12900 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
12910 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
12920 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
12930 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
12940 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
12950 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
12960 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
12970 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
12980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
12990 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
129a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
129b0 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
129c0 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
129d0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
129e0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
129f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
12a00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
12a10 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
12a20 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
12a30 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
12a40 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
12a50 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
12a60 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
12a70 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
12a80 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
12a90 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
12aa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
12ab0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
12ac0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
12ad0 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
12ae0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
12af0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
12b00 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
12b10 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
12b20 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
12b30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
12b40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
12b50 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
12b60 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
12b70 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
12b80 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
12b90 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
12ba0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
12bb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
12bc0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
12bd0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
12be0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
12bf0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
12c00 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
12c10 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
12c20 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
12c30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
12c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12c50 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12c60 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20  IDE       1001  
12c70 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
12c80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
12ca0 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32  LE_FKEY     1002
12cb0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
12cc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12cd0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
12ce0 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f  TRIGGER  1003  /
12cf0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a  * int int* */...
12d00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12d10 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
12d20 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
12d30 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
12d40 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
12d50 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
12d60 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
12d70 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
12d80 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
12d90 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
12da0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
12db0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
12dc0 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
12dd0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
12de0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
12df0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
12e00 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
12e10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
12e20 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
12e30 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
12e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12e50 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
12e60 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
12e70 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
12e80 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
12e90 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
12ea0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
12eb0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
12ec0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
12ed0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
12ee0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
12ef0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
12f00 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
12f10 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
12f20 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
12f30 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
12f40 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
12f50 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
12f60 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
12f70 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
12f80 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
12f90 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
12fa0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
12fb0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
12fc0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
12fd0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
12fe0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
12ff0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
13000 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
13010 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
13020 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
13030 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
13040 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
13050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13060 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
13070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
13080 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76   ^As of SQLite v
13090 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68  ersion 3.7.7, th
130a0 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72  is routines.** r
130b0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20  ecords the last 
130c0 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20  insert rowid of 
130d0 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61  both ordinary ta
130e0 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61  bles and [virtua
130f0 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49  l tables]..** ^I
13100 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
13110 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
13120 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
13130 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
13140 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
13150 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
13160 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
13170 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
13180 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
13190 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
131a0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
131b0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
131c0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
131d0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
131e0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
131f0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
13200 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
13210 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
13220 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
13230 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
13240 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
13250 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
13260 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
13270 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
13280 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
13290 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
132a0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
132b0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
132c0 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
132d0 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
132e0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
132f0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
13300 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
13310 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
13320 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
13330 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
13340 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
13350 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
13360 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
13370 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
13380 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
13390 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
133a0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
133b0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
133c0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
133d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
133e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
133f0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
13400 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
13410 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
13420 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
13430 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
13440 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
13450 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
13460 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
13470 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
13480 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
13490 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
134a0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
134b0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
134c0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
134d0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
134e0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
134f0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
13500 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
13510 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
13520 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
13530 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
13540 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
13550 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
13560 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
13570 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
13580 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
13590 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
135a0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
135b0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
135c0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
135d0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
135e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
135f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
13600 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
13610 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
13620 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
13630 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
13640 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
13650 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
13660 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
13670 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
13680 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
13690 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
136a0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
136b0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
136c0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
136d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
136e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
136f0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
13700 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
13710 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
13720 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
13730 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
13740 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
13750 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
13760 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
13770 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13780 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
13790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
137a0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
137b0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
137c0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
137d0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
137e0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
137f0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
13800 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
13810 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
13820 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
13830 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
13840 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
13850 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
13860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13870 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
13880 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13890 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
138a0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
138b0 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
138c0 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
138d0 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
138e0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
138f0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
13900 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
13910 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
13920 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
13930 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
13940 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
13950 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
13960 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
13970 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
13980 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
13990 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
139a0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
139b0 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
139c0 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
139d0 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
139e0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
139f0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
13a00 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
13a10 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
13a20 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
13a30 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
13a40 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
13a50 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
13a60 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
13a70 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
13a80 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
13a90 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
13aa0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
13ab0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
13ac0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
13ad0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
13ae0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
13af0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
13b00 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
13b10 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
13b20 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
13b30 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
13b40 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
13b50 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
13b60 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
13b70 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
13b80 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
13b90 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
13ba0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
13bb0 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
13bc0 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
13bd0 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
13be0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
13bf0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
13c00 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
13c10 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
13c20 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
13c30 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
13c40 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
13c50 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
13c60 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
13c70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
13c80 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
13c90 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
13ca0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
13cb0 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
13cc0 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
13cd0 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
13ce0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
13cf0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
13d00 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
13d10 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
13d20 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
13d30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
13d40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
13d50 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
13d60 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
13d70 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
13d80 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
13d90 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
13da0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
13db0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
13dc0 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
13dd0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
13de0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
13df0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
13e00 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
13e10 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
13e20 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
13e30 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
13e40 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
13e50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
13e60 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
13e70 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
13e80 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
13e90 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
13ea0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
13eb0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
13ec0 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
13ed0 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
13ee0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
13ef0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
13f00 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
13f10 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
13f20 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
13f30 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
13f40 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
13f50 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
13f60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
13f70 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
13f80 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13f90 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
13fa0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
13fb0 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
13fc0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
13fd0 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
13fe0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
13ff0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
14000 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
14010 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
14020 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
14030 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
14040 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
14050 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
14060 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
14070 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
14080 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
14090 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
140a0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
140b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
140c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
140d0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
140e0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
140f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14100 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
14110 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
14120 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14130 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14140 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
14150 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
14160 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
14170 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
14180 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
14190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
141a0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
141b0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
141c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
141d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
141e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
141f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
14200 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
14210 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
14220 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
14230 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
14240 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
14250 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
14260 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
14270 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
14280 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
14290 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
142a0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
142b0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
142c0 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
142d0 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
142e0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
142f0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
14300 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
14310 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
14320 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
14330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
14340 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
14350 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
14360 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
14370 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
14380 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
14390 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
143a0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
143b0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
143c0 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
143d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
143e0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
143f0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
14400 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
14410 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
14420 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
14430 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
14440 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
14450 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
14460 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
14470 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
14480 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
14490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
144a0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
144b0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
144c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
144d0 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
144e0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
144f0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
14500 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
14510 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
14520 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
14530 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
14540 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
14550 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
14560 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
14570 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
14580 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
14590 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
145a0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
145b0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
145c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
145d0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
145e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
145f0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
14600 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
14610 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
14620 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
14630 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
14640 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14650 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
14660 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
14670 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
14680 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
14690 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
146a0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
146b0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
146c0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
146d0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
146e0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
146f0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
14700 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
14710 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
14720 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
14730 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
14740 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
14750 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
14760 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
14770 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
14780 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
14790 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
147a0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
147b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
147c0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
147d0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
147e0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
147f0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
14800 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
14810 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
14820 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
14830 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
14840 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
14850 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
14860 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
14870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14880 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
14890 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
148a0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
148b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
148c0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
148d0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
148e0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
148f0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
14900 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
14910 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
14920 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
14930 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
14940 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
14950 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
14960 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
14970 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
14980 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
14990 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
149a0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
149b0 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
149c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
149d0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
149e0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
149f0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
14a00 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14a10 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
14a20 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
14a30 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
14a40 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
14a50 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
14a60 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
14a70 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
14a80 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
14a90 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
14aa0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
14ab0 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
14ac0 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
14ad0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
14ae0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
14af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14b00 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
14b10 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
14b20 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
14b30 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
14b40 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14b50 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
14b60 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
14b70 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
14b80 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
14b90 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
14ba0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
14bb0 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
14bc0 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
14bd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
14be0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
14bf0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
14c00 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
14c10 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
14c20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
14c30 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
14c40 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
14c50 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
14c60 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
14c70 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
14c80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
14c90 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
14ca0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
14cb0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
14cc0 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
14cd0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
14ce0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
14cf0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
14d00 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
14d10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
14d20 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
14d30 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
14d40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
14d50 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
14d60 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
14d70 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
14d80 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
14d90 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
14da0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
14db0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
14dc0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
14dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14de0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
14df0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
14e00 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
14e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
14e20 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
14e30 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
14e40 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
14e50 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
14e60 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
14e70 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
14e80 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
14e90 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
14ea0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
14eb0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
14ec0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
14ed0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
14ee0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
14ef0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
14f00 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
14f10 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
14f20 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
14f30 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
14f40 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
14f50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
14f60 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
14f70 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
14f80 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
14f90 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
14fa0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
14fb0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
14fc0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
14fd0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
14fe0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
14ff0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
15000 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
15010 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
15020 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
15030 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
15040 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
15050 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
15060 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
15070 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
15080 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
15090 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
150a0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
150b0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
150c0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
150d0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
150e0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
150f0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
15100 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
15110 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
15120 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
15130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
15140 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
15150 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
15160 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
15170 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
15180 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
15190 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
151a0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
151b0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
151c0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
151d0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
151e0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
151f0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
15200 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
15210 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
15220 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
15230 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
15240 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
15250 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
15260 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
15270 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
15280 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
15290 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
152a0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
152b0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
152c0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
152d0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
152e0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
152f0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
15300 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
15310 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
15320 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
15330 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
15340 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
15350 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
15360 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
15370 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
15380 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
15390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
153a0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
153b0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
153c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
153d0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
153e0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
153f0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
15400 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
15410 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
15420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
15430 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
15440 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
15450 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
15460 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
15470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
15480 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
15490 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
154a0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
154b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
154c0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
154d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
154e0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
154f0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
15500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
15510 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
15520 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
15530 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
15540 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
15550 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
15560 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
15570 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
15580 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
15590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
155a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
155b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
155c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
155d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
155e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
155f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
15600 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
15610 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
15620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
15630 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
15640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
15650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
15660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
15670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
15680 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
15690 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
156a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
156b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
156c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
156d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
156e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
156f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
15700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
15710 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
15720 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
15730 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
15740 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
15750 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
15760 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
15770 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
15780 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
15790 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
157a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
157b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
157c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
157d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
157e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
157f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
15800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
15810 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
15820 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
15830 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
15840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
15850 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
15860 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
15870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
15880 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
15890 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
158a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
158b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
158c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
158d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
158e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
158f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
15900 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
15910 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
15920 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
15930 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
15940 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
15950 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
15960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
15970 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
15980 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
15990 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
159a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
159b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
159c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
159d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
159e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
159f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
15a00 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
15a10 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
15a20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
15a30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
15a40 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
15a50 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
15a60 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
15a70 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
15a80 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
15a90 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
15aa0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
15ab0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
15ac0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
15ad0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
15ae0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
15af0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
15b00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
15b10 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
15b20 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
15b30 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
15b40 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
15b50 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
15b60 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
15b70 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
15b80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
15b90 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
15ba0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
15bb0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
15bc0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
15bd0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
15be0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
15bf0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
15c00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
15c10 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
15c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
15c30 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
15c40 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
15c50 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
15c60 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
15c70 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
15c80 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
15c90 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
15ca0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
15cb0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
15cc0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
15cd0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
15ce0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
15cf0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
15d00 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
15d10 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
15d20 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
15d30 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
15d40 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
15d50 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
15d60 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
15d70 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
15d80 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
15d90 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
15da0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
15db0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
15dc0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
15dd0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
15de0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
15df0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
15e00 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
15e10 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
15e20 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
15e30 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
15e40 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
15e50 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
15e60 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
15e70 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
15e80 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
15e90 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
15ea0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
15eb0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
15ec0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
15ed0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
15ee0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
15ef0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
15f00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
15f10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
15f20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
15f30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
15f40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
15f50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
15f60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
15f70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
15f80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
15f90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
15fa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
15fb0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
15fc0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
15fd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
15fe0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
15ff0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
16000 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
16010 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
16020 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
16030 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
16040 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
16050 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
16060 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
16070 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
16080 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
16090 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
160a0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
160b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
160c0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
160d0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
160e0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
160f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16100 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
16110 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
16120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
16130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
16140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
16150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
16160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
16170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
16180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
161a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
161b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
161c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
161d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
161e0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
161f0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
16200 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
16210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
16220 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
16230 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
16240 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
16250 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
16260 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
16270 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
16280 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
16290 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
162a0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
162b0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
162c0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
162d0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
162e0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
162f0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
16300 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
16310 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
16320 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
16330 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
16340 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
16350 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
16360 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
16370 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
16380 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
16390 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
163a0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
163b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
163c0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
163d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
163e0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
163f0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
16400 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
16410 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
16420 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
16430 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
16440 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
16450 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
16460 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
16470 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16480 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
16490 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
164a0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
164b0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
164c0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
164d0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
164e0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
164f0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
16500 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
16510 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
16520 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
16530 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
16540 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
16550 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
16560 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
16570 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
16580 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
16590 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
165a0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
165b0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
165c0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
165d0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
165e0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
165f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
16600 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
16610 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
16620 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
16630 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
16640 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
16650 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
16660 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
16670 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
16680 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
16690 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
166a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
166b0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
166c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
166d0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
166e0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
166f0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
16700 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
16710 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
16720 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
16730 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
16740 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
16750 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
16760 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
16770 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
16780 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
16790 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
167a0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
167b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
167c0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
167d0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
167e0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
167f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
16800 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
16810 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
16820 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
16830 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
16840 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
16850 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
16860 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
16870 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
16880 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
16890 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
168a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
168b0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
168c0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
168d0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
168e0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
168f0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
16900 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
16910 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
16920 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
16930 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
16940 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
16950 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
16960 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
16970 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
16980 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
16990 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
169a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
169b0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
169c0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
169d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
169e0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
169f0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
16a00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
16a10 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
16a20 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
16a30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
16a40 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
16a50 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
16a60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
16a70 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
16a80 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
16a90 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
16aa0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16ab0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
16ac0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
16ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
16ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16af0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
16b00 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
16b10 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
16b20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
16b30 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
16b40 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
16b50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
16b60 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
16b70 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
16b80 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
16b90 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
16ba0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
16bb0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
16bc0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
16bd0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
16be0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
16bf0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
16c00 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
16c10 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
16c20 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
16c30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
16c40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
16c50 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
16c60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16c70 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
16c80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16c90 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
16ca0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
16cb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
16cc0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
16cd0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16ce0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
16cf0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16d00 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
16d10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16d20 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
16d30 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
16d40 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
16d50 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
16d60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
16d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16d80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
16d90 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
16da0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
16db0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
16dc0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
16dd0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
16de0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
16df0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
16e00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
16e10 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
16e20 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
16e30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
16e40 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
16e50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
16e60 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
16e70 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
16e80 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
16e90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
16ea0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
16eb0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
16ec0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
16ed0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
16ee0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
16ef0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
16f00 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
16f10 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
16f20 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
16f30 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
16f40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
16f50 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
16f60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
16f70 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
16f80 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
16f90 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
16fa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
16fb0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
16fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
16fd0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
16fe0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
16ff0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
17000 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
17010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
17020 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
17030 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
17040 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
17050 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
17060 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
17070 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
17080 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
17090 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
170a0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
170b0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
170c0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
170d0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
170e0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
170f0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
17100 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
17110 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
17120 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
17130 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
17140 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
17150 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
17160 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
17170 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
17180 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
17190 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
171a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
171b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
171c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
171d0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
171e0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
171f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
17200 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
17210 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
17220 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
17230 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
17240 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
17250 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
17260 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
17270 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
17280 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
17290 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
172a0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
172b0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
172c0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
172d0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
172e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
172f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
17300 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
17310 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
17320 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
17330 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
17340 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
17350 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
17360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
17370 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
17380 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
17390 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
173a0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
173b0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
173c0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
173d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
173e0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
173f0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
17400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17410 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
17420 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
17430 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
17440 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
17450 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
17460 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
17470 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
17480 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
17490 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
174a0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
174b0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
174c0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
174d0 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
174e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
174f0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
17500 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
17510 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
17520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
17530 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
17540 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
17550 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
17560 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17570 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
17580 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
17590 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
175a0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
175b0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
175c0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
175d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
175e0 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
175f0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17600 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
17610 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
17620 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
17630 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
17640 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
17650 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
17660 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
17670 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
17680 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
17690 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
176a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
176b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
176c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
176d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
176e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
176f0 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
17700 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
17710 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
17720 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
17730 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
17740 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
17750 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
17760 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
17770 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
17780 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
17790 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
177a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
177b0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
177c0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
177d0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
177e0 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
177f0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
17800 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
17810 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
17820 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
17830 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
17840 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
17850 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
17860 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
17870 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
17880 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
17890 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
178a0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
178b0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
178c0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
178d0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
178e0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
178f0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
17900 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
17910 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
17920 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
17930 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
17940 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
17950 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
17960 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
17970 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
17980 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17990 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
179a0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
179b0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
179c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
179d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
179e0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
179f0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
17a00 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
17a10 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
17a20 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
17a30 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
17a40 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
17a50 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
17a60 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
17a70 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
17a80 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
17a90 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
17aa0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
17ab0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
17ac0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
17ad0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
17ae0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
17af0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
17b00 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
17b10 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
17b20 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
17b30 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
17b40 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
17b50 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
17b60 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
17b70 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
17b80 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
17b90 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
17ba0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
17bb0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
17bc0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
17bd0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
17be0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
17bf0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
17c00 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
17c10 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
17c20 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
17c30 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
17c40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
17c50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17c60 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
17c70 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
17c80 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
17c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
17ca0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
17cb0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
17cc0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
17cd0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
17ce0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17cf0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
17d00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
17d10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
17d20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
17d30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
17d40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
17d50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
17d60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
17d70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
17d80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17d90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
17da0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
17db0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
17dc0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
17dd0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
17de0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
17df0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
17e00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
17e10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17e20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
17e30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
17e40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
17e50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
17e60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
17e70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
17e80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
17e90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
17ea0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
17eb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
17ec0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
17ed0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
17ee0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
17ef0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
17f00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
17f10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
17f20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
17f30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
17f40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
17f50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
17f60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
17f70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
17f80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
17f90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
17fa0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
17fb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
17fc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
17fd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
17fe0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
17ff0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
18000 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
18010 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
18020 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
18030 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
18040 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
18050 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
18060 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
18070 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
18080 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
18090 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
180a0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
180b0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
180c0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
180d0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
180e0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
180f0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
18100 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
18110 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
18120 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
18130 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
18140 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
18150 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
18160 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
18170 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
18180 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
18190 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
181a0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
181b0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
181c0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
181d0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
181e0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
181f0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
18200 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
18210 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
18220 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
18230 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
18240 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
18250 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
18260 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
18270 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
18280 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
18290 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
182a0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
182b0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
182c0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
182d0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
182e0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
182f0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
18300 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
18310 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
18320 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
18330 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
18340 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
18350 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
18360 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
18370 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
18380 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
18390 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
183a0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
183b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
183c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
183d0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
183e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
183f0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
18400 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
18410 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
18420 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
18430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
18440 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
18450 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
18460 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
18470 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
18480 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
18490 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
184a0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
184b0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
184c0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
184d0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
184e0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
184f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18500 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
18510 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
18520 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
18530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
18540 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
18550 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
18560 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
18570 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
18580 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
18590 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
185a0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
185b0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
185c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
185d0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
185e0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
185f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
18600 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
18610 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
18620 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
18630 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
18640 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
18650 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
18660 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
18670 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
18680 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
18690 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
186a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
186b0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
186c0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
186d0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
186e0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
186f0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
18700 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
18710 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
18720 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
18730 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
18740 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
18750 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18760 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
18770 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
18780 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
18790 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
187a0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
187b0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
187c0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
187d0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
187e0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
187f0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
18800 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
18810 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
18820 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
18830 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
18840 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
18850 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
18860 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
18870 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
18880 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
18890 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
188a0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
188b0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
188c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
188d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
188e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
188f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
18900 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
18910 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
18920 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
18930 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
18940 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
18950 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
18960 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18970 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
18980 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
18990 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
189a0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
189b0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
189c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
189d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
189e0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
189f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
18a00 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
18a10 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
18a20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
18a30 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
18a40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
18a50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
18a60 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
18a70 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
18a80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
18a90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
18aa0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
18ab0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
18ac0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
18ad0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
18ae0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
18af0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
18b00 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
18b10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18b20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
18b30 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
18b40 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
18b50 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
18b60 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
18b70 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
18b80 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
18b90 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
18ba0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
18bb0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
18bc0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
18bd0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18be0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
18bf0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
18c00 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18c10 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
18c20 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
18c30 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
18c40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
18c50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
18c60 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
18c70 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
18c80 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
18c90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
18ca0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
18cb0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
18cc0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
18cd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
18ce0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
18cf0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
18d00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
18d10 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
18d20 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
18d30 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
18d40 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
18d50 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
18d60 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
18d70 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
18d80 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
18d90 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
18da0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
18db0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
18dc0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
18dd0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
18de0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
18df0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
18e00 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
18e10 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
18e20 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
18e30 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
18e40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
18e50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
18e60 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
18e70 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
18e80 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
18e90 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
18ea0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
18eb0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
18ec0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
18ed0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
18ee0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
18ef0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
18f00 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
18f10 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
18f20 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
18f30 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
18f40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
18f50 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
18f60 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
18f70 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
18f80 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
18f90 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
18fa0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
18fb0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
18fc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
18fd0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
18fe0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
18ff0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
19000 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
19010 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
19020 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
19030 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
19040 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
19050 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
19060 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19070 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
19080 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
19090 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
190a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
190b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
190c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
190d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
190e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
190f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
19100 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
19110 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
19120 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
19130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
19140 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
19150 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
19160 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
19170 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
19180 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
19190 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
191a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
191b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
191c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
191d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
191e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
191f0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
19200 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
19210 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
19220 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
19230 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
19240 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
19250 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
19260 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
19270 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
19280 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
19290 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
192a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
192b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
192c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
192d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
192e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
192f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
19300 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
19310 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
19320 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
19330 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
19340 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
19350 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
19360 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
19370 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
19380 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
19390 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
193a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
193b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
193c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
193d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
193e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
193f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
19400 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
19410 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
19420 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
19430 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
19440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
19450 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
19460 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19470 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19480 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
19490 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
194a0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
194b0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
194c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
194d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
194e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
194f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
19500 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
19510 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
19520 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
19530 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
19540 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
19550 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
19560 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
19570 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
19580 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
19590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
195a0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
195b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
195c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
195d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
195e0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
195f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19600 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
19610 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
19620 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
19630 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
19640 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
19650 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
19660 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
19670 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
19680 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19690 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
196a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
196b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
196c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
196d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
196e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
196f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
19700 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
19710 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
19720 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
19730 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
19740 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
19750 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
19760 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
19770 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
19780 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
19790 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
197a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
197b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
197c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
197d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
197e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
197f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
19800 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
19810 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
19820 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
19830 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
19840 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
19850 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
19860 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
19870 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
19880 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
19890 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
198a0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
198b0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
198c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
198d0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
198e0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
198f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
19900 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
19910 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
19920 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
19930 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
19940 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
19950 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
19960 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
19970 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
19980 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
19990 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
199a0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
199b0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
199c0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
199d0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
199e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
199f0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
19a00 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
19a10 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
19a20 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
19a30 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
19a40 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
19a50 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
19a60 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
19a70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
19a80 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
19a90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19aa0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
19ab0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
19ac0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
19ad0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
19ae0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
19af0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
19b00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
19b10 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
19b20 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
19b30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
19b40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
19b50 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
19b60 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
19b70 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
19b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
19b90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
19ba0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
19bb0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
19bc0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
19bd0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
19be0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
19bf0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
19c00 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
19c10 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
19c20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19c30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
19c40 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
19c50 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
19c60 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
19c70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19c80 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
19c90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
19ca0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
19cb0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
19cc0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
19cd0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
19ce0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
19cf0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
19d00 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
19d10 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
19d20 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
19d30 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
19d40 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
19d50 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
19d60 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
19d70 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
19d80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19d90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
19da0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
19db0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
19dc0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
19dd0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
19de0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
19df0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
19e00 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
19e10 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
19e20 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
19e30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
19e40 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
19e50 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
19e60 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
19e70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
19e80 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
19e90 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
19ea0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
19eb0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
19ec0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
19ed0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
19ee0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
19ef0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19f00 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
19f10 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
19f20 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
19f30 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
19f40 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
19f50 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
19f60 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
19f70 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
19f80 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
19f90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19fa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19fb0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19fc0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
19fd0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
19fe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
19ff0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1a000 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1a010 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1a020 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1a030 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1a040 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1a050 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1a060 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1a070 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1a080 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1a090 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1a0a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1a0b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1a0c0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1a0d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1a0e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1a0f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1a100 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1a110 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a120 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1a130 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1a140 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1a150 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1a160 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1a170 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1a180 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1a190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1a1a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1a1b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1a1c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1a1d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1a1e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1a1f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1a200 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1a210 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1a220 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1a230 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1a240 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1a250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1a260 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1a270 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1a280 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1a290 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1a2a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1a2b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1a2c0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1a2d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1a2e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1a2f0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1a300 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1a310 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1a320 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1a330 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1a340 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1a350 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1a360 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1a370 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1a380 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1a390 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1a3a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1a3b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1a3c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1a3d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1a3e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1a3f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1a400 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1a410 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1a420 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1a430 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1a440 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1a450 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1a460 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1a470 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1a480 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1a490 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1a4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1a4b0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1a4c0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1a4d0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1a4e0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1a4f0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1a500 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1a510 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1a520 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1a530 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1a540 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1a550 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1a560 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1a570 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1a580 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1a590 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1a5a0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1a5b0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1a5c0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1a5d0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1a5e0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1a5f0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1a600 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1a610 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1a620 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1a630 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1a640 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1a650 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1a660 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1a670 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1a680 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1a690 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1a6a0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1a6b0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1a6c0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1a6d0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1a6e0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1a6f0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1a700 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1a710 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1a720 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1a730 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1a740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1a750 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1a760 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1a770 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1a780 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1a790 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1a7a0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1a7b0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1a7c0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1a7d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1a7e0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1a7f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1a800 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1a810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a820 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1a830 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1a840 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1a850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a860 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a880 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1a890 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1a8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1a8b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a8c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1a8d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1a8e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1a8f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1a900 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1a910 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1a920 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1a930 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1a940 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1a950 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1a960 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1a970 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1a980 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1a990 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1a9a0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1a9b0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1a9c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a9d0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1a9e0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1a9f0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1aa00 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1aa10 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1aa20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1aa30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1aa40 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1aa50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1aa60 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1aa70 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1aa80 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1aa90 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1aaa0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1aab0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1aac0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1aad0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1aae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1aaf0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1ab00 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1ab10 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1ab20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1ab30 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1ab40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1ab50 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1ab60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1ab70 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1ab80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1ab90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1aba0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1abb0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1abc0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1abd0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1abe0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1abf0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1ac00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1ac10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1ac20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1ac30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1ac40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ac50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1ac60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ac70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1ac80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1ac90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1aca0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1acb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1acc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1acd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ace0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1acf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1ad00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1ad10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ad20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1ad30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1ad40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1ad50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1ad60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1ad70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1ad80 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1ad90 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1ada0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1adb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1adc0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1add0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1ade0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1adf0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1ae00 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ae10 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1ae20 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1ae30 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1ae40 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1ae50 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1ae60 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1ae70 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1ae80 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1ae90 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1aea0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1aeb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1aec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1aed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1aee0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1aef0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1af00 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1af10 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1af20 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1af30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1af40 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1af50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1af60 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1af70 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1af80 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1af90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1afa0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1afb0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1afc0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1afd0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1afe0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1aff0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1b000 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1b010 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1b020 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1b030 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1b040 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1b050 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1b060 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1b070 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1b080 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1b090 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1b0a0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1b0b0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1b0c0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1b0d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1b0e0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1b0f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1b100 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1b110 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1b120 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1b130 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1b140 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1b150 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1b160 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1b170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1b180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b190 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1b1a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1b1b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1b1c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1b1d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1b1e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1b1f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1b200 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1b210 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1b220 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1b230 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1b240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b260 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1b270 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1b280 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1b290 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b2a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1b2b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1b2c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1b2d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b2e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b2f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1b300 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b310 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b320 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b330 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b340 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1b350 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1b360 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b370 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b380 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1b390 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1b3a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b3b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b3c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b3d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1b3e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1b3f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1b400 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1b410 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b420 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1b430 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1b440 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1b450 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b470 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1b480 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1b490 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1b4a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b4b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b4c0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1b4d0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1b4e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1b4f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b510 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1b520 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1b530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b550 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b560 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1b570 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1b580 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1b590 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b5b0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1b5c0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1b5d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b5e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b600 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1b610 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1b620 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1b630 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b650 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1b660 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1b670 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b680 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b690 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b6a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1b6b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1b6c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1b6d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b6e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b6f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1b700 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1b710 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1b720 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b730 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1b740 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1b750 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1b760 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1b770 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b780 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1b790 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1b7a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1b7b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b7c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b7d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1b7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1b7f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b800 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b810 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b820 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1b830 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1b840 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1b850 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1b860 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1b870 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1b880 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1b890 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b8a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1b8b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b8c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1b8d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1b8e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1b8f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b900 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b910 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1b920 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1b930 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1b940 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b960 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1b970 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1b980 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b990 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1b9a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b9b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1b9c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1b9d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1b9e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b9f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ba00 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1ba10 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1ba20 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1ba30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ba40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ba50 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1ba60 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1ba70 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1ba80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ba90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1baa0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1bab0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1bac0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1bad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1bae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1baf0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1bb00 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1bb10 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1bb20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1bb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1bb40 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1bb50 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1bb60 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1bb70 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1bb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1bb90 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1bba0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1bbb0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1bbc0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1bbd0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1bbe0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1bbf0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1bc00 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1bc10 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1bc20 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1bc30 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1bc40 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1bc50 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1bc60 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1bc70 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1bc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1bc90 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1bca0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1bcb0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1bcc0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1bcd0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1bce0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1bcf0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1bd00 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1bd10 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1bd20 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1bd30 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1bd40 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1bd50 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1bd60 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1bd70 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1bd80 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1bd90 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1bda0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1bdb0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1bdc0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1bdd0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1bde0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1bdf0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1be00 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1be10 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1be20 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1be30 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1be40 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1be50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1be60 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1be70 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1be80 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1be90 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1bea0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1beb0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1bec0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1bed0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1bee0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1bef0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1bf00 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1bf10 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1bf20 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1bf30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1bf40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bf50 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1bf60 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1bf70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1bf80 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1bf90 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1bfa0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1bfb0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1bfc0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1bfd0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1bfe0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1bff0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1c000 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1c010 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1c020 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1c030 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1c040 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1c050 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1c060 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1c070 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1c080 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1c090 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1c0a0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1c0b0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1c0c0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1c0d0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1c0e0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1c0f0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1c100 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1c110 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1c120 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1c130 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1c140 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1c150 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1c160 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1c170 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1c180 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1c190 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1c1a0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1c1b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1c1c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1c1d0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1c1e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1c1f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1c200 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1c210 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1c220 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1c230 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1c240 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1c250 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1c260 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1c270 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1c280 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c290 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1c2a0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1c2b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c2c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c2d0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1c2e0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1c2f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1c300 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1c310 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1c320 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1c330 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1c340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1c350 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1c360 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1c370 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1c380 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1c390 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1c3a0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1c3b0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1c3c0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1c3d0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1c3e0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1c3f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1c400 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1c410 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1c420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1c430 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1c440 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1c450 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1c460 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1c470 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1c480 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1c490 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1c4a0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1c4b0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1c4c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1c4d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1c4e0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1c4f0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1c500 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1c510 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1c520 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1c530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1c540 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1c550 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1c560 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1c570 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1c580 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1c590 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1c5a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c5b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1c5c0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1c5d0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1c5e0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1c5f0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1c600 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1c610 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c620 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1c630 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1c640 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1c650 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1c660 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1c670 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1c680 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1c690 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1c6a0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1c6b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1c6c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1c6d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1c6e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1c6f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1c700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c710 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1c720 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1c730 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1c740 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1c750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1c760 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1c770 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1c780 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1c790 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1c7a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1c7b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1c7c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1c7d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1c7e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c7f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1c800 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1c810 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c820 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1c830 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1c840 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1c850 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1c860 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1c870 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1c880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1c890 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1c8a0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1c8b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1c8c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1c8d0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1c8e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1c8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c900 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1c910 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1c920 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1c930 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1c940 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1c950 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1c960 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1c970 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1c980 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1c990 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1c9a0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1c9b0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1c9c0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1c9d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1c9e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1c9f0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1ca00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1ca10 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1ca20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1ca30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1ca40 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1ca50 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1ca60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ca70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1ca80 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1ca90 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1caa0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1cab0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1cac0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1cad0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1cae0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1caf0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1cb00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1cb10 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1cb20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1cb30 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1cb40 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1cb50 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1cb60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1cb70 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1cb80 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1cb90 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1cba0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1cbb0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1cbc0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1cbd0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1cbe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1cbf0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1cc00 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1cc10 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1cc20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1cc30 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1cc40 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1cc50 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1cc60 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1cc70 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1cc80 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1cc90 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1cca0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1ccb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ccc0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1ccd0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1cce0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1ccf0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1cd00 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1cd10 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1cd20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1cd30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1cd40 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1cd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1cd60 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1cd70 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1cd80 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1cd90 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1cda0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1cdb0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1cdc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1cdd0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1cde0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1cdf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1ce00 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1ce10 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1ce20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1ce30 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1ce40 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1ce50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1ce60 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1ce70 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1ce80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1ce90 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1cea0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1ceb0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1cec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1ced0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1cee0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1cef0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1cf00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1cf10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1cf20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1cf30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1cf40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1cf50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1cf60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1cf70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1cf80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1cf90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1cfa0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1cfb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1cfc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1cfd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1cfe0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1cff0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1d000 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1d010 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1d020 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1d030 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1d040 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1d050 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1d060 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1d070 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1d080 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d090 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1d0a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1d0b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1d0c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1d0d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1d0e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d0f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1d100 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1d110 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1d120 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1d130 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1d140 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1d150 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1d160 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1d170 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1d180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d190 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1d1a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1d1b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1d1c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d1d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1d1e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1d1f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1d200 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1d210 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1d220 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1d230 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1d240 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1d250 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1d260 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1d270 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1d280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1d290 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d2a0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1d2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d2c0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1d2d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1d2e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1d2f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1d300 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1d310 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1d320 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d330 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1d340 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1d350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1d360 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1d370 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1d380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d390 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1d3a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1d3b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1d3c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1d3d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1d3e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1d3f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1d400 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1d410 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d420 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1d430 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1d440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d450 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1d460 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1d470 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1d480 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1d490 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1d4a0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1d4b0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1d4c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1d4d0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1d4e0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1d4f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1d500 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1d510 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d520 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1d530 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1d540 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1d550 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1d560 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1d570 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1d580 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d590 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1d5a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1d5b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1d5c0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1d5d0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1d5e0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1d5f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1d600 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1d610 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1d620 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1d630 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1d640 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1d650 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1d660 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1d670 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1d680 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1d690 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1d6a0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1d6b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1d6c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1d6d0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1d6e0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1d6f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1d700 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1d710 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1d720 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1d730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1d740 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1d750 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d760 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1d770 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1d780 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1d790 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1d7a0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1d7b0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1d7c0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1d7d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1d7e0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1d7f0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1d800 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1d810 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1d820 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1d830 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1d840 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1d850 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1d860 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1d870 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1d880 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1d890 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1d8a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1d8b0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1d8c0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1d8d0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1d8e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1d8f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1d900 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1d910 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1d920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d930 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1d940 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1d950 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1d960 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1d970 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1d980 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1d990 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1d9a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1d9b0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1d9c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1d9d0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1d9e0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1d9f0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
1da00 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
1da10 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
1da20 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1da30 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
1da40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1da50 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
1da60 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
1da70 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1da80 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
1da90 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
1daa0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
1dab0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
1dac0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
1dad0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
1dae0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
1daf0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
1db00 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
1db10 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
1db20 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
1db30 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1db40 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
1db50 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1db60 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
1db70 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
1db80 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
1db90 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1dba0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
1dbb0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
1dbc0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
1dbd0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
1dbe0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
1dbf0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1dc00 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1dc10 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
1dc20 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
1dc30 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
1dc40 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
1dc50 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
1dc60 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
1dc70 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
1dc80 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
1dc90 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
1dca0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
1dcb0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
1dcc0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
1dcd0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
1dce0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
1dcf0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
1dd00 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
1dd10 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
1dd20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1dd30 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
1dd40 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
1dd50 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
1dd60 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
1dd70 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
1dd80 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
1dd90 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
1dda0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
1ddb0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
1ddc0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
1ddd0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
1dde0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
1ddf0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
1de00 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
1de10 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
1de20 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
1de30 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
1de40 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
1de50 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
1de60 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
1de70 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
1de80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
1de90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
1dea0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
1deb0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
1dec0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
1ded0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
1dee0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
1def0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
1df00 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
1df10 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
1df20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
1df30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
1df40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1df50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
1df60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
1df70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
1df80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
1df90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
1dfa0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
1dfb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
1dfc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
1dfd0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
1dfe0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
1dff0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
1e000 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
1e010 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
1e020 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
1e030 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
1e040 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
1e050 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
1e060 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
1e070 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
1e080 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
1e090 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1e0a0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
1e0b0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
1e0c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1e0d0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
1e0e0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
1e0f0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
1e100 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
1e110 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
1e120 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
1e130 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
1e140 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
1e150 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
1e160 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
1e170 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
1e180 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
1e190 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
1e1a0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
1e1b0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
1e1c0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
1e1d0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
1e1e0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
1e1f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
1e200 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1e210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1e220 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
1e230 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
1e240 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
1e250 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1e260 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
1e270 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20  ", "rw" or.**   
1e280 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74    "rwc". Attempt
1e290 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
1e2a0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
1e2b0 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20   is an error)^. 
1e2c0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
1e2d0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
1e2e0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1e2f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1e300 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
1e310 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
1e320 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1e330 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
1e340 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
1e350 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
1e360 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1e370 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  o sqlite3_prepar
1e380 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  e_v2(). ^If the 
1e390 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
1e3a0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
1e3b0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
1e3c0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e3d0 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
1e3e0 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
1e3f0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1e400 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
1e410 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
1e420 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
1e430 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
1e440 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
1e450 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
1e460 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1e470 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
1e480 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
1e490 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
1e4a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
1e4b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1e4c0 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20  _v2() is .**    
1e4d0 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20   used, it is an 
1e4e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
1e4f0 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65   a value for the
1e500 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1e510 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20  that is .**     
1e520 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
1e530 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
1e540 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67  fied by the flag
1e550 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
1e560 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61  third .**     pa
1e570 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20  rameter..**.**  
1e580 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
1e590 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
1e5a0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1e5b0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
1e5c0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
1e5d0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
1e5e0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
1e5f0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
1e600 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1e610 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1e620 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1e630 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
1e640 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1e650 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
1e660 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
1e670 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
1e680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
1e690 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
1e6a0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
1e6b0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
1e6c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1e6d0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
1e6e0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
1e6f0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1e700 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
1e710 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
1e720 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
1e730 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
1e740 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
1e750 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72  es any behaviour
1e760 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
1e770 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
1e780 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1e790 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
1e7a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1e7b0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
1e7c0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
1e7d0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
1e7e0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
1e7f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
1e800 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
1e810 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
1e820 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1e830 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
1e840 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
1e850 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
1e860 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
1e870 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
1e880 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
1e890 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
1e8a0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
1e8b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1e8c0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
1e8d0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
1e8e0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
1e8f0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
1e900 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
1e910 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
1e920 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
1e930 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
1e940 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
1e950 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
1e960 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1e970 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1e980 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
1e990 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1e9a0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1e9b0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
1e9c0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1e9d0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
1e9e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1e9f0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
1ea00 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
1ea10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
1ea20 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
1ea30 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
1ea40 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1ea50 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
1ea60 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
1ea70 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
1ea80 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
1ea90 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
1eaa0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
1eab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
1eac0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
1ead0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
1eae0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
1eaf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
1eb00 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
1eb10 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
1eb20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
1eb30 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
1eb40 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
1eb50 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
1eb60 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
1eb70 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
1eb80 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
1eb90 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
1eba0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
1ebb0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
1ebc0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
1ebd0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
1ebe0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
1ebf0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
1ec00 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
1ec10 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
1ec20 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
1ec30 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
1ec40 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
1ec50 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
1ec60 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1ec70 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
1ec80 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
1ec90 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1eca0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
1ecb0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
1ecc0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
1ecd0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
1ece0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
1ecf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1ed00 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
1ed10 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
1ed20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
1ed30 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
1ed40 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
1ed50 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
1ed60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1ed70 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
1ed80 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
1ed90 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
1eda0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1edb0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
1edc0 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
1edd0 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
1ede0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
1edf0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
1ee00 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1ee10 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
1ee20 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
1ee30 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
1ee40 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
1ee50 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
1ee60 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
1ee70 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
1ee80 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
1ee90 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
1eea0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
1eeb0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
1eec0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
1eed0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1eee0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
1eef0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
1ef00 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
1ef10 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
1ef20 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
1ef30 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
1ef40 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
1ef50 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
1ef60 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
1ef70 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
1ef80 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
1ef90 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
1efa0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
1efb0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
1efc0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
1efd0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1efe0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
1eff0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
1f000 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
1f010 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
1f020 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
1f030 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
1f040 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
1f050 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
1f060 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
1f070 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1f080 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1f090 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1f0a0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1f0b0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1f0c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1f0d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1f0e0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1f0f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1f100 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1f110 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1f120 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1f130 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1f140 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1f150 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1f160 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1f170 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1f180 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1f190 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1f1a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1f1b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1f1c0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74  pen_v2()..*/.int
1f1d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1f1e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1f1f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1f200 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1f210 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1f220 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1f230 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1f240 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1f250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1f260 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1f270 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1f280 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1f290 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1f2a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1f2b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1f2c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1f2d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1f2e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1f2f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1f300 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1f310 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1f320 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1f330 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1f340 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1f350 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1f360 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1f370 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1f380 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1f390 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1f3a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1f3b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1f3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f3d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
1f3e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
1f3f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ers.**.** This i
1f400 73 20 61 20 75 74 69 6c 69 74 79 20 72 6f 75 74  s a utility rout
1f410 69 6e 65 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  ine, useful to V
1f420 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1f430 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 73 0a  ns, that checks.
1f440 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
1f450 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
1f460 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
1f470 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
1f480 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
1f490 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
1f4a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
1f4b0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
1f4c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1f4d0 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72  The zFilename ar
1f4e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 66 69  gument is the fi
1f4f0 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
1f500 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
1f510 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Open().** method
1f520 20 6f 66 20 61 20 56 46 53 20 69 6d 70 6c 65 6d   of a VFS implem
1f530 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a  entation.  The z
1f540 50 61 72 61 6d 20 61 72 67 75 6d 65 6e 74 20 69  Param argument i
1f550 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f560 65 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  e.** query param
1f570 65 74 65 72 20 77 65 20 73 65 65 6b 2e 20 20 54  eter we seek.  T
1f580 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
1f590 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
1f5a0 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70   the zParam.** p
1f5b0 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
1f5c0 78 69 73 74 73 2e 20 20 49 66 20 74 68 65 20 70  xists.  If the p
1f5d0 61 72 61 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f  arameter does no
1f5e0 74 20 65 78 69 73 74 2c 20 74 68 69 73 20 72 6f  t exist, this ro
1f5f0 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73  utine.** returns
1f600 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f610 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  .**.** If the zF
1f620 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1f630 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
1f640 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  n is not a point
1f650 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 0a 2a  er that SQLite.*
1f660 2a 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  * passed into th
1f670 65 20 78 4f 70 65 6e 20 56 46 53 20 6d 65 74 68  e xOpen VFS meth
1f680 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
1f690 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
1f6a0 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65  utine.** is unde
1f6b0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1f6c0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
1f6d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1f6e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
1f6f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
1f700 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
1f710 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
1f720 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
1f730 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
1f740 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
1f750 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1f760 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
1f770 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1f780 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
1f790 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
1f7a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1f7b0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
1f7c0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
1f7d0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
1f7e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1f7f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1f800 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
1f810 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
1f820 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
1f830 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
1f840 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
1f850 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1f860 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
1f870 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
1f880 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
1f890 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1f8a0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
1f8b0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
1f8c0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
1f8d0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
1f8e0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
1f8f0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1f900 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
1f910 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1f920 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
1f930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1f940 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
1f950 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
1f960 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
1f970 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
1f980 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
1f990 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
1f9a0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1f9b0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
1f9c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
1f9d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1f9e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1f9f0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1fa00 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1fa10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1fa20 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1fa30 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1fa40 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1fa50 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1fa60 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1fa70 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1fa80 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1fa90 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1faa0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1fab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1fac0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
1fad0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
1fae0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1faf0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
1fb00 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
1fb10 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
1fb20 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
1fb30 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
1fb40 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
1fb50 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
1fb60 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
1fb70 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
1fb80 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
1fb90 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
1fba0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
1fbb0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
1fbc0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
1fbd0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
1fbe0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
1fbf0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
1fc00 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
1fc10 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
1fc20 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
1fc30 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
1fc40 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
1fc50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1fc60 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
1fc70 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1fc80 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
1fc90 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1fca0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
1fcb0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
1fcc0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
1fcd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
1fce0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
1fcf0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
1fd00 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
1fd10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
1fd20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
1fd30 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
1fd40 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
1fd50 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
1fd60 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
1fd70 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
1fd80 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
1fd90 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
1fda0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
1fdb0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
1fdc0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
1fdd0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
1fde0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
1fdf0 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
1fe00 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
1fe10 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
1fe20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1fe30 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1fe40 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
1fe50 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
1fe60 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
1fe70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1fe80 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
1fe90 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1fea0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
1feb0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
1fec0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
1fed0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
1fee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1fef0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
1ff00 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
1ff10 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
1ff20 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
1ff30 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
1ff40 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
1ff50 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
1ff60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ff70 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
1ff80 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
1ff90 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
1ffa0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
1ffb0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
1ffc0 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
1ffd0 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
1ffe0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
1fff0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
20000 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
20010 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
20020 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20030 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
20040 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
20050 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
20060 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
20070 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
20080 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20090 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
200a0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
200b0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
200c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
200d0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
200e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
200f0 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
20100 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
20110 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
20120 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
20130 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
20140 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
20150 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
20160 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
20170 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
20180 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
20190 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
201a0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
201b0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
201c0 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
201d0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
201e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
201f0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
20200 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
20210 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
20220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20230 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
20240 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
20250 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
20260 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
20270 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
20280 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
20290 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
202a0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
202b0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
202c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
202d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
202e0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
202f0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
20300 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
20310 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
20320 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
20330 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
20340 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
20350 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
20360 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
20370 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
20380 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
20390 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
203a0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
203b0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
203c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
203d0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
203e0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
203f0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
20400 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
20410 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
20420 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
20430 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
20440 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
20450 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
20460 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
20470 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
20480 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
20490 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
204a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
204b0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
204c0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
204d0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
204e0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
204f0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
20500 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
20510 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
20520 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
20530 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
20540 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
20550 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
20560 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
20570 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
20580 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
20590 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
205a0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
205b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
205c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
205d0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
205e0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
205f0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
20600 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
20610 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
20620 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
20630 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
20640 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
20650 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
20660 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
20670 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
20680 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
20690 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
206a0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
206b0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
206c0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
206d0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
206e0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
206f0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
20700 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
20710 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
20720 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
20730 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
20740 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
20750 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
20760 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
20770 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
20780 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
20790 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
207a0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
207b0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
207c0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
207d0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
207e0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
207f0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
20800 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
20810 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
20820 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
20830 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
20840 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
20850 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
20860 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
20870 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
20880 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
20890 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
208a0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
208b0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
208c0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
208d0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
208e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
208f0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
20900 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
20910 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
20920 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
20930 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
20940 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
20950 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
20960 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
20970 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
20980 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
20990 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
209a0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
209b0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
209c0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
209d0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
209e0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
209f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
20a00 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
20a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20a20 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
20a30 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
20a40 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
20a50 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
20a60 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
20a70 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
20a80 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
20a90 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
20aa0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
20ab0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
20ac0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
20ad0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
20ae0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
20af0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
20b00 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
20b10 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
20b20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
20b30 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
20b40 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
20b50 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
20b60 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
20b70 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
20b80 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20b90 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20ba0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
20bb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20bc0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
20bd0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
20be0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
20bf0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
20c00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
20c10 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
20c20 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20c30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
20c40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20c50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20c60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20c70 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
20c80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
20c90 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
20ca0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
20cb0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
20cc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20cd0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
20ce0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
20cf0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
20d00 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
20d10 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
20d20 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
20d30 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
20d40 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
20d50 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
20d60 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
20d70 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
20d80 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
20d90 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
20da0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20db0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
20dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20dd0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
20de0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
20df0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
20e00 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
20e10 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
20e20 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
20e30 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
20e40 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
20e50 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
20e60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20e70 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
20e80 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
20e90 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
20ea0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20eb0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
20ec0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
20ed0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
20ee0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20ef0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
20f00 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
20f10 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20f20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
20f30 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
20f40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
20f50 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
20f60 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
20f70 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
20f80 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
20f90 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
20fa0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
20fb0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
20fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
20fd0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
20fe0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
20ff0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
21000 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
21010 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
21020 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
21030 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
21040 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21050 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
21060 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
21070 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
21080 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
21090 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
210a0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
210b0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
210c0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
210d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
210e0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
210f0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
21100 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
21110 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
21120 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
21130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
21140 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
21150 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
21160 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
21170 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
21180 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21190 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
211a0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
211b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
211c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
211d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
211e0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
211f0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
21200 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
21210 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
21220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
21230 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
21240 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
21250 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
21260 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
21270 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
21280 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
21290 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
212a0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
212b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
212c0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
212d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
212e0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
212f0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
21300 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
21310 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
21320 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
21330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21340 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
21350 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
21360 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
21370 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
21380 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
21390 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
213a0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
213b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
213c0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
213d0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
213e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
213f0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
21400 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
21410 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
21420 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
21430 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
21440 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
21450 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
21460 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
21470 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
21480 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
21490 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
214a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
214b0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
214c0 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
214d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
214e0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
214f0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
21500 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
21510 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
21520 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
21530 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
21540 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
21550 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
21560 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
21570 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
21580 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
21590 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
215a0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
215b0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
215c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
215d0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
215e0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
215f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21600 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
21610 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
21620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
21630 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
21640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21650 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
21660 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
21670 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
21680 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
21690 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
216a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
216b0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
216c0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
216d0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
216e0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
216f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21700 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
21710 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
21720 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
21730 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
21740 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21750 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
21760 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
21770 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
21780 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
21790 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
217a0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
217b0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
217c0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
217d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
217e0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
217f0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
21800 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
21810 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
21820 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
21830 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
21840 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
21850 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
21860 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
21870 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
21880 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
21890 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
218a0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
218b0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
218c0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
218d0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
218e0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
218f0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
21900 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
21910 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
21920 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
21930 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
21940 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
21950 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
21960 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
21970 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
21980 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
21990 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
219a0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
219b0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
219c0 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
219d0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
219e0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
219f0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
21a00 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
21a10 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
21a20 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
21a30 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
21a40 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
21a50 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
21a60 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
21a70 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
21a80 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
21a90 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
21aa0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
21ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
21ac0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
21ad0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
21ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21af0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
21b00 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
21b10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
21b20 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
21b30 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
21b40 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
21b50 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
21b60 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
21b70 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
21b80 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
21b90 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
21ba0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
21bb0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
21bc0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
21bd0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
21be0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
21bf0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
21c00 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
21c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
21c20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
21c30 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
21c40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
21c50 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
21c60 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
21c70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
21c80 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
21c90 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
21ca0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
21cb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
21cc0 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
21cd0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
21ce0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
21cf0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21d00 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
21d10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21d20 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
21d30 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
21d40 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
21d50 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
21d60 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
21d70 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
21d80 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
21d90 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
21da0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
21db0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
21dc0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
21dd0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
21de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21df0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
21e00 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
21e10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
21e20 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
21e30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
21e40 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
21e50 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
21e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e70 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
21e80 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
21e90 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
21ea0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
21eb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
21ec0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
21ed0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
21ee0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
21ef0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
21f00 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
21f10 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
21f20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
21f30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
21f40 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
21f50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
21f60 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
21f70 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
21f80 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
21f90 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
21fa0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
21fb0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
21fc0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
21fd0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
21fe0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
21ff0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
22000 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
22010 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
22020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
22030 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
22040 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
22050 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
22060 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
22070 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
22080 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
22090 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
220a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
220b0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
220c0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
220d0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
220e0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
220f0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
22100 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
22110 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
22120 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
22130 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
22140 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
22150 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
22160 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
22170 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
22180 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
22190 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
221a0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
221b0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
221c0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
221d0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
221e0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
221f0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
22200 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
22210 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
22220 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
22230 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
22240 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
22250 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
22260 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
22270 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
22280 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
22290 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
222a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
222b0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
222c0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
222d0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
222e0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
222f0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
22300 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
22310 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
22320 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
22330 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
22340 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
22350 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
22360 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
22370 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
22380 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
22390 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
223a0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
223b0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
223c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
223d0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
223e0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
223f0 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
22400 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
22410 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
22420 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
22430 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
22440 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
22450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
22460 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22470 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22480 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22490 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
224a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
224b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
224c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
224d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
224e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
224f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22500 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22510 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
22520 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
22530 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
22540 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
22550 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
22560 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
22570 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22580 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22590 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
225a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
225b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
225c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
225d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
225e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
225f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22600 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
22610 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
22620 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
22630 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22640 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22650 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
22660 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22670 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22680 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22690 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
226a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
226b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
226c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
226d0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
226e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
226f0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
22700 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
22710 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
22720 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
22730 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
22740 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
22750 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
22760 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
22770 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
22780 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
22790 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
227a0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
227b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
227c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
227d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
227e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
227f0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
22800 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22810 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22820 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22830 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
22840 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
22850 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
22860 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22870 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
22880 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
22890 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
228a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
228b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
228c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
228d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
228e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
228f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22900 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22910 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22920 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
22930 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
22940 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
22950 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
22960 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
22970 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
22980 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
22990 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
229a0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
229b0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
229c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
229d0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
229e0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
229f0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22a00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22a10 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
22a20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22a30 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
22a40 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
22a50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
22a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22a70 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
22a80 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
22a90 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
22aa0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
22ab0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
22ac0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
22ad0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
22ae0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
22af0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
22b00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22b10 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
22b20 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
22b30 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
22b40 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
22b50 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
22b60 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
22b70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
22b80 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
22b90 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
22ba0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
22bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
22bc0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
22bd0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
22be0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
22bf0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
22c00 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
22c10 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
22c20 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
22c30 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
22c40 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
22c50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
22c60 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
22c70 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22c80 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
22c90 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
22ca0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
22cb0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
22cc0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
22cd0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
22ce0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
22cf0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
22d00 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
22d10 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
22d20 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
22d30 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
22d40 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
22d50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
22d60 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
22d70 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
22d80 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
22d90 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
22da0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
22db0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
22dc0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
22dd0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
22de0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
22df0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
22e00 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
22e10 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
22e20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
22e30 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
22e40 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
22e50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
22e60 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
22e70 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
22e80 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
22e90 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
22ea0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
22eb0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
22ec0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
22ed0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
22ee0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
22ef0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
22f00 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
22f10 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
22f20 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
22f30 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
22f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
22f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22f60 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
22f70 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
22f80 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
22f90 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
22fa0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
22fb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22fc0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
22fd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22fe0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22ff0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
23000 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
23010 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
23020 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
23030 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
23040 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23050 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
23060 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
23070 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23080 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
23090 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
230a0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
230b0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
230c0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
230d0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
230e0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
230f0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
23100 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
23110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23120 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
23130 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
23140 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
23150 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
23160 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
23170 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
23180 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
23190 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
231a0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
231b0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
231c0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
231d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
231e0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
231f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
23200 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
23210 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
23220 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
23230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
23240 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
23250 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
23260 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
23270 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
23280 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
23290 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
232a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
232b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
232c0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
232d0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
232e0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
232f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
23300 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
23310 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
23320 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
23330 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
23340 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
23350 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
23360 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
23370 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
23380 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
23390 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
233a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
233b0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
233c0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
233d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
233e0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
233f0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23400 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
23410 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
23420 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
23430 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
23440 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
23450 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
23460 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
23470 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
23480 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
23490 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
234a0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
234b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
234c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
234d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
234e0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
234f0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
23500 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
23510 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
23520 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
23530 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
23540 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
23550 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
23560 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
23570 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
23580 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
23590 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
235a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
235b0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
235c0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
235d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
235e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
235f0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
23600 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
23610 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
23620 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
23630 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
23640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
23650 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
23660 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
23670 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
23680 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
23690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
236a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
236b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
236c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
236d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
236e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
236f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
23700 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
23710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
23720 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
23730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
23740 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
23750 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
23760 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
23770 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
23780 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23790 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
237a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
237b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
237c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
237d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
237e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
237f0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
23800 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
23810 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
23820 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
23830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
23840 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
23850 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
23860 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23870 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
23880 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
23890 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
238a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
238b0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
238c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
238d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
238e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
238f0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
23900 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
23910 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
23920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
23930 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
23940 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
23950 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
23960 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
23970 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
23980 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
23990 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
239a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
239b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
239c0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
239d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
239e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
239f0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
23a00 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
23a10 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
23a20 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
23a30 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
23a40 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
23a50 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
23a60 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
23a70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
23a80 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
23a90 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
23aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
23ab0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
23ac0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
23ad0 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
23ae0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
23af0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
23b00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23b10 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
23b20 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
23b30 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
23b40 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
23b50 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
23b60 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
23b70 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
23b80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
23b90 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
23ba0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
23bb0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
23bc0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
23bd0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
23be0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
23bf0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
23c00 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
23c10 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
23c20 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
23c30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
23c40 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
23c50 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
23c60 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
23c70 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
23c80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
23c90 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
23ca0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
23cb0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
23cc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
23cd0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
23ce0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
23cf0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
23d00 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
23d10 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
23d20 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
23d30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23d40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
23d50 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23d60 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
23d70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
23d80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
23d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
23da0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
23db0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
23dc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
23dd0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
23de0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
23df0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
23e00 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
23e10 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
23e20 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
23e30 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
23e40 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
23e50 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
23e60 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
23e70 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
23e80 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
23e90 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
23ea0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
23eb0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
23ec0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
23ed0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
23ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23ef0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
23f00 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
23f10 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
23f20 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
23f30 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
23f40 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
23f50 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
23f60 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
23f70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
23f80 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
23f90 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
23fa0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
23fb0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
23fc0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
23fd0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
23fe0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
23ff0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
24000 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
24010 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
24020 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
24030 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
24040 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
24050 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
24060 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
24070 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
24080 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
24090 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
240a0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
240b0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
240c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
240d0 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
240e0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
240f0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
24100 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
24110 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
24120 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
24130 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
24140 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
24150 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
24160 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
24170 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
24180 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
24190 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
241a0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
241b0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
241c0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
241d0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
241e0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
241f0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
24200 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
24210 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
24220 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
24230 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
24240 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
24250 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
24260 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
24270 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
24280 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
24290 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
242a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
242b0 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
242c0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
242d0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
242e0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
242f0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
24300 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
24310 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
24320 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
24330 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
24340 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
24350 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
24360 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
24370 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
24380 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
24390 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
243a0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
243b0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
243c0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
243d0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
243e0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
243f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
24400 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
24410 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
24420 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
24430 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
24440 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
24450 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
24460 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
24470 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
24480 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
24490 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
244a0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
244b0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
244c0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
244d0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
244e0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
244f0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
24500 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
24510 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
24520 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
24530 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
24540 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
24550 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
24560 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
24570 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
24580 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
24590 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
245a0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
245b0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
245c0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
245d0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
245e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
245f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
24600 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
24610 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
24620 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24630 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
24640 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
24650 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
24660 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
24670 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
24680 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
24690 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
246a0 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
246b0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
246c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
246d0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
246e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
246f0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
24700 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
24710 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
24720 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
24730 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
24740 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
24750 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
24760 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
24770 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
24780 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
24790 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
247a0 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
247b0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
247c0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
247d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
247e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
247f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24800 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
24810 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
24820 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
24830 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
24840 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
24850 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
24860 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
24870 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
24880 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
24890 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
248a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
248b0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
248c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
248d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
248e0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
248f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
24900 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
24910 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
24920 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24930 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
24940 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24950 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
24960 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
24970 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
24980 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
24990 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
249a0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
249b0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
249c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
249d0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
249e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
249f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24a00 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
24a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
24a20 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
24a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
24a40 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
24a50 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
24a60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
24a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24a80 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
24a90 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
24aa0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
24ab0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
24ac0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24ad0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
24ae0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
24af0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
24b00 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
24b10 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24b20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
24b30 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
24b40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
24b50 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
24b60 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
24b70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
24b80 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
24b90 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
24ba0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
24bb0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
24bc0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
24bd0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
24be0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
24bf0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
24c00 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
24c10 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
24c20 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
24c30 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
24c40 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
24c50 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
24c60 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
24c70 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
24c80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24c90 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
24ca0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
24cb0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
24cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
24cd0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
24ce0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
24cf0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
24d00 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
24d10 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
24d20 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
24d30 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
24d40 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
24d50 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
24d60 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
24d70 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
24d80 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
24d90 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
24da0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
24db0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
24dc0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
24dd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24de0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
24df0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
24e00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
24e10 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
24e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24e30 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
24e40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24e50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
24e60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
24e70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
24e80 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
24e90 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
24ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24eb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24ec0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
24ed0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
24ee0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24ef0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
24f00 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
24f10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24f20 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
24f30 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
24f40 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
24f50 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
24f60 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
24f70 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
24f80 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
24f90 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
24fa0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
24fb0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
24fc0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
24fd0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
24fe0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
24ff0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
25000 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
25010 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
25020 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
25030 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
25040 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
25050 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
25060 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
25070 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
25080 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
25090 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
250a0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
250b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
250c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
250d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
250e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
250f0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
25100 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
25110 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
25120 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
25130 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
25140 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
25150 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
25160 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
25170 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
25180 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
25190 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
251a0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
251b0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
251c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
251d0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
251e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
251f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
25200 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
25210 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
25220 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
25230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25240 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25250 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25260 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25270 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
25280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25290 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
252a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
252b0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
252c0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
252d0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
252e0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
252f0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
25300 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
25310 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
25320 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
25330 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
25340 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
25350 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
25360 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
25370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
25380 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25390 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
253a0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
253b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
253c0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
253d0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
253e0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
253f0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
25400 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
25410 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
25420 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
25430 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
25440 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
25450 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
25460 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
25470 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25490 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
254a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
254b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
254c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
254d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
254e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
254f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25500 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25510 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
25520 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
25530 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
25540 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
25550 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
25560 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25570 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
25580 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
25590 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
255a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
255b0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
255c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
255d0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
255e0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
255f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
25600 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
25610 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
25620 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
25630 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
25640 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
25650 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
25660 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
25670 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
25680 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
25690 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
256a0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
256b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
256c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
256d0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
256e0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
256f0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
25700 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
25710 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
25720 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
25730 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
25740 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
25750 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
25760 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
25770 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
25780 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
25790 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
257a0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
257b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
257c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
257d0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
257e0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
257f0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
25800 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
25810 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
25820 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
25830 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
25840 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
25850 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
25860 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
25870 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
25880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
258a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
258b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
258c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
258d0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
258e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
258f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
25900 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
25910 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
25920 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
25930 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25940 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
25950 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
25960 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25970 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
25980 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
25990 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
259a0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
259b0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
259c0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
259d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
259e0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
259f0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
25a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25a10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
25a20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
25a30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
25a40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
25a50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
25a60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
25a70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
25a80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25a90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
25aa0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
25ab0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
25ac0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
25ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
25ae0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
25af0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
25b00 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
25b10 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
25b20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
25b30 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
25b40 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
25b50 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
25b60 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
25b70 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
25b80 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
25b90 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
25ba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
25bb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
25bc0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
25bd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
25be0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25bf0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
25c00 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
25c10 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
25c20 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
25c30 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
25c40 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
25c50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
25c60 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
25c70 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
25c80 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
25c90 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
25ca0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
25cb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
25cd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25ce0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
25cf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25d00 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
25d10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
25d20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25d30 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
25d40 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
25d50 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
25d60 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
25d70 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
25d80 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
25d90 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
25da0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
25db0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
25dc0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
25dd0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
25de0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
25df0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
25e00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
25e10 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
25e20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
25e30 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
25e40 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
25e50 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
25e60 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
25e70 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
25e80 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
25e90 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
25ea0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
25eb0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
25ec0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
25ed0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
25ee0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
25ef0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
25f00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
25f10 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
25f20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25f30 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
25f40 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
25f50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25f60 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
25f70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
25f80 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
25f90 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
25fa0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
25fb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
25fc0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
25fd0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
25fe0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
25ff0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
26000 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
26010 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
26020 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
26030 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
26040 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
26050 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
26060 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
26070 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
26080 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
26090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
260a0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
260b0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
260c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
260d0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
260e0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
260f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
26100 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
26110 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
26120 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
26130 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
26140 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
26150 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
26160 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
26170 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
26180 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
26190 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
261a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
261b0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
261c0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
261d0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
261e0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
261f0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
26200 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
26210 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
26220 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
26230 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
26240 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
26250 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
26260 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
26270 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
26280 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
26290 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
262a0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
262b0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
262c0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
262d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
262e0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
262f0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
26300 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
26310 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
26320 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
26330 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
26340 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
26350 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
26360 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
26370 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
26380 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
26390 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
263a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
263b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
263c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
263d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
263e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
263f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
26400 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
26410 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
26420 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
26430 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
26440 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
26450 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
26460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26470 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
26480 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
26490 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
264a0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
264b0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
264c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
264d0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
264e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
264f0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
26500 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
26510 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
26520 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
26530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26540 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
26550 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
26560 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
26570 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
26580 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
26590 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
265a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
265b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
265c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
265d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
265e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
265f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26600 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
26610 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
26620 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
26630 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
26640 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
26660 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
26670 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
26680 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26690 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
266a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
266b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
266c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
266d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
266e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
266f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
26700 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
26710 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
26720 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
26730 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
26740 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
26750 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26760 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
26770 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
26780 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
26790 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
267a0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
267b0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
267c0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
267d0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
267e0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
267f0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
26800 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
26810 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
26820 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
26830 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
26840 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
26850 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
26860 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
26870 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
26880 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
26890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
268a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
268b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
268c0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
268d0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
268e0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
268f0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
26900 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
26910 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
26920 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
26930 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
26940 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
26950 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
26960 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
26970 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
26980 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
26990 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
269a0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
269b0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
269c0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
269d0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
269e0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
269f0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
26a00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
26a10 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
26a20 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
26a30 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
26a40 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
26a50 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
26a60 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
26a70 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
26a80 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
26a90 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
26aa0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
26ab0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
26ac0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
26ad0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
26ae0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
26af0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
26b00 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
26b10 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
26b20 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
26b30 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
26b40 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
26b50 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
26b60 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
26b70 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
26b80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
26b90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
26ba0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
26bb0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
26bc0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26bd0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
26be0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26bf0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
26c00 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
26c10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
26c20 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
26c30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26c40 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
26c50 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
26c60 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
26c70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
26c80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26c90 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
26ca0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
26cb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
26cc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
26cd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26ce0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
26cf0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
26d00 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
26d10 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
26d20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
26d30 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
26d40 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
26d50 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
26d60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26d70 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
26d80 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
26d90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
26da0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
26db0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
26dc0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
26dd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26de0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26df0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
26e00 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
26e10 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
26e20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26e30 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
26e40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
26e50 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
26e60 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
26e70 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
26e80 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
26e90 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
26ea0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
26eb0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
26ec0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
26ed0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
26ee0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
26ef0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
26f00 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
26f10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
26f20 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
26f30 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
26f40 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
26f50 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
26f60 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
26f70 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26f80 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
26f90 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
26fa0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
26fb0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26fc0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
26fd0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
26fe0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
26ff0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
27000 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
27010 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
27020 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
27030 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
27040 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
27050 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
27060 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
27070 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
27080 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
27090 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
270a0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
270b0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
270c0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
270d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
270e0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
270f0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
27100 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
27110 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
27120 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
27130 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
27140 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
27150 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
27160 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
27170 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
27180 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
27190 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
271a0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
271b0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
271c0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
271d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
271e0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
271f0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
27200 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
27210 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27220 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
27230 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
27240 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
27250 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
27260 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
27270 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
27280 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
27290 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
272a0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
272b0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
272c0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
272d0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
272e0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
272f0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
27300 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
27310 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
27320 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
27330 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
27340 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
27350 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
27360 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
27370 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
27380 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
27390 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
273a0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
273b0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
273c0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
273d0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
273e0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
273f0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
27400 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
27410 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
27420 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
27430 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
27440 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
27450 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
27460 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
27470 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
27480 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
27490 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
274a0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
274b0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
274c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
274d0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
274e0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
274f0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
27500 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
27510 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
27520 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27530 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
27540 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
27550 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
27560 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
27570 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
27580 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
27590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
275a0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
275b0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
275c0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
275d0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
275e0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
275f0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
27600 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
27610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27620 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
27630 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
27640 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
27650 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
27660 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
27670 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
27680 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
27690 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
276a0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
276b0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
276c0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
276d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
276e0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
276f0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
27700 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
27710 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
27720 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
27730 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
27740 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
27750 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
27760 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
27770 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27780 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
27790 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
277a0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
277b0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
277c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
277d0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
277e0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
277f0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
27800 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
27810 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
27820 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27830 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
27840 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
27850 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
27860 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
27870 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
27880 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
27890 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
278a0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
278b0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
278c0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
278d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
278e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
278f0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
27900 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
27910 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
27920 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
27930 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
27940 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
27950 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
27960 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
27970 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
27980 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
27990 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
279a0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
279b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
279c0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
279d0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
279e0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
279f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
27a00 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
27a10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
27a20 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
27a30 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
27a40 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
27a50 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
27a60 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
27a70 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
27a80 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
27a90 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
27aa0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
27ab0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
27ac0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
27ad0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
27ae0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
27af0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
27b00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27b10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
27b20 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
27b30 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
27b40 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
27b50 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
27b60 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
27b70 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
27b80 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
27b90 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
27ba0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
27bb0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
27bc0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
27bd0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
27be0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
27bf0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
27c00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
27c10 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
27c20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27c30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
27c40 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
27c50 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
27c60 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
27c70 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
27c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27c90 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
27ca0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
27cb0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
27cc0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
27cd0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
27ce0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
27cf0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
27d00 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
27d10 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
27d20 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
27d30 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
27d40 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27d50 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27d60 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
27d70 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
27d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
27d90 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
27da0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
27db0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
27dc0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
27dd0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
27de0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
27df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27e00 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
27e10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27e20 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
27e30 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
27e40 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
27e50 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
27e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
27e70 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
27e80 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
27e90 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
27ea0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
27eb0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
27ec0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27ed0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
27ee0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
27ef0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
27f00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
27f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
27f20 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
27f30 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
27f40 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
27f50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
27f60 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
27f70 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
27f80 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
27f90 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
27fa0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
27fb0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
27fc0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
27fd0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
27fe0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
27ff0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
28000 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
28010 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
28020 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
28030 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
28040 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
28050 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
28060 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
28070 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
28080 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
28090 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
280a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
280b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
280c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
280d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
280e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
280f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
28100 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
28110 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
28120 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
28130 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
28140 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
28150 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
28160 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
28170 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28180 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
28190 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
281a0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
281b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
281c0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
281d0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
281e0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
281f0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
28200 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
28210 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
28220 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
28230 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
28240 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
28250 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
28260 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
28270 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
28280 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
28290 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
282a0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
282b0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
282c0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
282d0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
282e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
282f0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
28300 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
28310 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
28320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
28330 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
28340 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
28350 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
28360 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
28370 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
28380 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
28390 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
283a0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
283b0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
283c0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
283d0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
283e0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
283f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28400 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
28410 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
28420 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
28430 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
28440 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
28450 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
28460 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
28470 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
28480 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
28490 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
284a0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
284b0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
284c0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
284d0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
284e0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
284f0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
28500 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
28510 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
28520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28530 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
28540 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
28550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
28560 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
28570 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
28580 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
28590 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
285a0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
285b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
285c0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
285d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
285e0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
285f0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
28600 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
28610 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
28620 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28630 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
28640 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
28650 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
28660 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
28670 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
28680 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
28690 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
286a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
286b0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
286c0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
286d0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
286e0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
286f0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
28700 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
28710 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
28720 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
28730 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
28740 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
28750 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
28760 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
28770 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
28780 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
28790 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
287a0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
287b0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
287c0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
287d0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
287e0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
287f0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
28800 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
28810 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
28820 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28830 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
28840 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
28850 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
28860 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
28870 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
28880 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
28890 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
288a0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
288b0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
288c0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
288d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
288e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
288f0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
28900 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
28910 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
28920 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
28930 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
28940 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
28950 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28960 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
28970 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
28980 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
28990 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
289a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
289b0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
289c0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
289d0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
289e0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
289f0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
28a00 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
28a10 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
28a20 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
28a30 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
28a40 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
28a50 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
28a60 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
28a70 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
28a80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
28a90 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
28aa0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
28ab0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
28ac0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
28ad0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
28ae0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
28af0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
28b00 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
28b10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
28b20 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28b30 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
28b40 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
28b50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
28b60 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
28b70 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
28b80 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
28b90 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
28ba0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
28bb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
28bc0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
28bd0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
28be0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
28bf0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
28c00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
28c10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28c20 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
28c30 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
28c40 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28c50 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
28c60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
28c70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
28c80 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
28c90 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
28ca0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
28cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28cc0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
28cd0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
28ce0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
28cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28d00 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
28d10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
28d20 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
28d30 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
28d40 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
28d50 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
28d60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
28d70 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
28d80 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
28d90 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
28da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28db0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
28dc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
28dd0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
28de0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
28df0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
28e00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28e10 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
28e20 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
28e30 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
28e40 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
28e50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
28e60 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
28e70 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
28e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28e90 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
28ea0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
28eb0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
28ec0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
28ed0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
28ee0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
28ef0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
28f00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
28f10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
28f20 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
28f30 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
28f40 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
28f50 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
28f60 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
28f70 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
28f80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28f90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
28fa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
28fb0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
28fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28fd0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
28fe0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
28ff0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
29000 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29010 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
29020 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29030 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
29040 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
29050 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
29060 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
29070 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
29080 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
29090 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
290a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
290b0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
290c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
290d0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
290e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
290f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
29100 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
29110 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
29120 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
29130 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
29140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29150 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
29160 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
29170 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
29180 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
29190 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
291a0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
291b0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
291c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
291d0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
291e0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
291f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
29200 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
29210 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
29220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
29230 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
29240 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29250 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29260 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
29270 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29280 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
29290 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
292a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
292b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
292c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
292d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
292e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
292f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
29300 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
29310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29320 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
29330 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
29340 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
29350 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
29360 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
29370 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
29380 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
29390 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
293a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
293b0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
293c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
293d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
293e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
293f0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
29400 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
29410 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
29420 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
29430 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
29440 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
29450 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
29460 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
29470 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
29480 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
29490 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
294a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
294b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
294c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
294d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
294e0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
294f0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
29500 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
29510 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
29520 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
29530 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
29540 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
29550 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
29560 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
29570 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
29580 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
29590 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
295a0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
295b0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
295c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
295d0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
295e0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
295f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
29600 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
29610 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
29620 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
29630 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
29640 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
29650 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
29660 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
29670 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
29680 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
29690 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
296a0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
296b0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
296c0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
296d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
296e0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
296f0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
29700 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
29710 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
29720 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
29730 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
29740 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
29750 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
29760 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
29770 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
29780 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
29790 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
297a0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
297b0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
297c0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
297d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
297e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
297f0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
29800 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
29810 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
29820 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
29830 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
29840 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
29850 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29860 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
29870 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
29880 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
29890 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
298a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
298b0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
298c0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
298d0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
298e0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
298f0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29900 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
29910 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
29920 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
29930 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
29940 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
29950 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
29960 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
29970 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
29980 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
29990 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
299a0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
299b0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
299c0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
299d0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
299e0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
299f0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
29a00 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
29a10 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
29a20 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
29a30 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
29a40 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
29a50 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
29a60 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
29a70 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
29a80 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
29a90 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
29aa0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
29ab0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
29ac0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
29ad0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
29ae0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
29af0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
29b00 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
29b10 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
29b20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29b30 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
29b40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
29b50 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
29b60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29b70 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
29b80 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
29b90 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
29ba0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
29bb0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
29bc0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
29bd0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
29be0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
29bf0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29c00 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
29c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29c20 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
29c30 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
29c40 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
29c50 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
29c60 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
29c70 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
29c80 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
29c90 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
29ca0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
29cb0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
29cc0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
29cd0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29ce0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
29cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29d00 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
29d10 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29d20 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29d30 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
29d40 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
29d50 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29d60 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
29d70 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
29d80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
29d90 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29da0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
29db0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
29dc0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
29dd0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
29de0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
29df0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
29e00 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
29e10 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
29e20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
29e30 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
29e40 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
29e50 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
29e60 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
29e70 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
29e80 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
29e90 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
29ea0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
29eb0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
29ec0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
29ed0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
29ee0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
29ef0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
29f00 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
29f10 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
29f20 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
29f30 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
29f40 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
29f50 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
29f60 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
29f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
29f80 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
29f90 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
29fa0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
29fb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
29fc0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
29fd0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
29fe0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
29ff0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2a000 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2a010 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2a020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2a030 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2a040 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2a050 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2a060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a070 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2a080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a090 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2a0a0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2a0b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2a0c0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2a0d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2a0e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2a0f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a100 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2a110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2a120 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2a130 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2a140 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2a150 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2a160 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2a170 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2a180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a190 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2a1a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a1b0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2a1c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2a1d0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2a1e0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2a1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a200 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2a210 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2a220 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2a230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a240 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2a250 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2a260 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a270 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2a280 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2a290 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2a2a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2a2b0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2a2c0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2a2d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2a2e0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2a2f0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2a300 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2a310 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2a320 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2a330 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2a340 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2a350 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2a360 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2a370 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2a380 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2a390 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2a3a0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2a3b0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2a3c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2a3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a3e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2a3f0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2a400 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2a410 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2a420 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2a430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2a440 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2a450 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2a460 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2a470 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2a480 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2a490 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2a4a0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2a4b0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2a4c0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2a4d0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2a4e0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2a4f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2a500 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2a510 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2a520 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2a530 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2a540 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2a550 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a560 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2a570 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a580 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2a590 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2a5a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a5b0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2a5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a5d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a5e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2a5f0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2a600 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2a610 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a620 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a630 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2a640 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a650 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2a660 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2a670 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2a680 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a690 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2a6a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a6b0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2a6c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a6d0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2a6e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a6f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2a700 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a710 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a720 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2a730 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a740 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2a750 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a760 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2a770 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a790 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2a7a0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2a7b0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2a7c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a7d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a7e0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2a7f0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a800 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2a810 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2a820 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2a830 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2a840 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2a850 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2a860 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2a870 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2a880 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2a890 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2a8a0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2a8b0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2a8c0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2a8d0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2a8e0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2a8f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2a900 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2a910 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2a920 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2a930 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a940 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2a950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a960 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2a970 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2a980 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2a990 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2a9a0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2a9b0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2a9c0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2a9d0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2a9e0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2a9f0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2aa00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2aa10 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2aa20 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2aa30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2aa40 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2aa50 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2aa60 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2aa70 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2aa80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2aa90 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2aaa0 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2aab0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2aac0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2aad0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2aae0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2aaf0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2ab00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2ab10 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2ab20 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2ab30 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2ab40 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2ab50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2ab60 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2ab70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ab80 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2ab90 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2aba0 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2abb0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2abc0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2abd0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2abe0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2abf0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2ac00 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2ac10 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2ac20 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2ac30 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2ac40 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2ac50 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2ac60 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ac70 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2ac80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ac90 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2aca0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2acb0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2acc0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2acd0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2ace0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2acf0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2ad00 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2ad10 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2ad20 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2ad30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2ad40 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2ad50 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2ad60 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2ad70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2ad80 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2ad90 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2ada0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2adb0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2adc0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2add0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2ade0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2adf0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2ae00 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2ae10 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2ae20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae30 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2ae40 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2ae50 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2ae60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2ae70 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2ae80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2ae90 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2aea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aeb0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2aec0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2aed0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2aee0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2aef0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2af00 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2af10 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2af20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2af30 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2af40 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2af50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2af60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2af70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2af80 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2af90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2afa0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2afb0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2afc0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2afd0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2afe0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2aff0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2b000 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b010 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2b020 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2b030 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2b040 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2b050 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2b060 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2b070 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2b080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2b090 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2b0a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2b0b0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2b0c0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2b0d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2b0e0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2b0f0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2b100 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2b110 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2b120 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b130 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2b140 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2b150 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2b160 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2b170 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2b180 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2b190 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2b1a0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2b1b0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2b1c0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2b1d0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2b1e0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2b1f0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2b200 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2b210 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2b220 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2b230 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2b240 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2b250 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2b260 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2b270 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2b280 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2b290 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2b2a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2b2b0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2b2c0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2b2d0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2b2e0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2b2f0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2b300 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2b310 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2b320 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2b330 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2b340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b350 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2b360 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2b370 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2b380 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2b390 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2b3a0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2b3b0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2b3c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2b3d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b3e0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2b3f0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2b400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b410 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2b420 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2b430 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2b440 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2b450 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2b460 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2b470 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2b480 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2b490 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2b4a0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2b4b0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2b4c0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2b4d0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2b4e0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2b4f0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2b500 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2b510 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2b520 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2b530 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2b540 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2b550 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2b560 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2b570 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2b580 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2b590 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2b5a0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2b5b0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2b5c0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2b5d0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2b5e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2b5f0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2b600 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2b610 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2b620 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2b630 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2b640 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2b650 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2b660 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2b670 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2b680 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2b690 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2b6a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2b6b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2b6c0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2b6d0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2b6e0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2b6f0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2b700 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2b710 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2b720 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2b730 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2b740 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2b750 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2b760 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2b770 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2b780 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2b790 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2b7a0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2b7b0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2b7c0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2b7d0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2b7e0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2b7f0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2b800 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2b810 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2b820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2b830 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2b840 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2b850 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2b860 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2b870 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2b880 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2b890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2b8a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b8b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2b8c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2b8d0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2b8e0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2b8f0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2b900 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2b910 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2b920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2b930 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2b940 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2b950 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2b960 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2b970 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2b980 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2b990 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2b9a0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2b9b0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2b9c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b9d0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2b9e0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2b9f0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2ba00 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2ba10 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2ba20 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2ba30 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2ba40 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2ba50 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2ba60 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2ba70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2ba80 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2ba90 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2baa0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2bab0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2bac0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2bad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2bae0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2baf0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2bb00 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2bb10 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2bb20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2bb30 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2bb40 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2bb50 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2bb60 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2bb70 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2bb80 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2bb90 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2bba0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2bbb0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2bbc0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2bbd0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2bbe0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2bbf0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2bc00 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2bc10 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2bc20 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2bc30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2bc40 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2bc50 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2bc60 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2bc70 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2bc80 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2bc90 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2bca0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2bcb0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2bcc0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2bcd0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2bce0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2bcf0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2bd00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2bd10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bd20 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2bd30 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2bd40 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2bd50 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2bd60 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2bd70 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2bd80 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2bd90 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2bda0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2bdb0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2bdc0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2bdd0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2bde0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2bdf0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2be00 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2be10 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2be20 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2be30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2be40 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2be50 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2be60 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2be70 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2be80 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2be90 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2bea0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2beb0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2bec0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2bed0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2bee0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2bef0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2bf00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2bf10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bf20 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2bf30 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2bf40 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2bf50 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2bf60 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2bf70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2bf80 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2bf90 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2bfa0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2bfb0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2bfc0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2bfd0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2bfe0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2bff0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2c000 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2c010 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2c020 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2c030 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2c040 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2c050 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2c060 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2c070 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2c080 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2c090 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2c0a0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2c0b0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2c0c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2c0d0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2c0e0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2c0f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2c100 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2c110 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2c120 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2c130 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2c140 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2c150 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2c160 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2c170 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2c180 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2c190 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2c1a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2c1b0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2c1c0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2c1d0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2c1e0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2c1f0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2c200 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2c210 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2c220 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2c230 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2c240 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2c250 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2c260 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c270 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2c280 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2c290 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c2a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2c2b0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2c2c0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2c2d0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2c2e0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2c2f0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2c300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c310 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2c320 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2c330 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2c340 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2c350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2c360 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
2c370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c380 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2c390 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2c3a0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2c3b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2c3c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2c3d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2c3e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2c3f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c400 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c410 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2c420 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2c430 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2c440 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2c450 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2c460 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2c470 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2c480 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2c490 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2c4a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2c4b0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2c4c0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2c4d0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2c4e0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2c4f0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2c500 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c510 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c520 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2c530 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c540 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c550 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2c560 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2c570 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2c580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c590 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2c5a0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2c5b0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2c5c0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2c5d0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c5e0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2c5f0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2c600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c610 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c620 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c630 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2c640 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c650 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c660 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2c670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2c680 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2c690 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2c6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2c6b0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2c6c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2c6d0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2c6e0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2c6f0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2c700 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2c710 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2c720 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2c730 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2c740 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2c750 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c760 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2c770 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c780 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2c790 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c7a0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2c7b0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2c7c0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2c7d0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2c7e0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2c7f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c800 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2c810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c820 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2c830 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2c840 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2c850 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2c860 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2c870 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2c880 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2c890 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2c8a0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2c8b0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2c8c0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2c8d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2c8e0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2c8f0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2c900 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2c910 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2c920 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2c930 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2c940 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2c950 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2c960 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2c970 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2c980 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2c990 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2c9a0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2c9b0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2c9c0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2c9d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2c9e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2c9f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2ca00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2ca10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2ca20 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2ca30 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2ca40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2ca50 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2ca60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2ca70 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ca80 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2ca90 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2caa0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2cab0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2cac0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2cad0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2cae0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2caf0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2cb00 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2cb10 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2cb20 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2cb30 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2cb40 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2cb50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2cb60 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2cb70 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2cb80 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2cb90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2cba0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2cbb0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2cbc0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2cbd0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2cbe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2cbf0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2cc00 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2cc10 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2cc20 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2cc30 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2cc40 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2cc50 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2cc60 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2cc70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2cc80 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2cc90 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2cca0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2ccb0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2ccc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2ccd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2cce0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ccf0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2cd00 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2cd10 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2cd20 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2cd30 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2cd40 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2cd50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2cd60 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2cd70 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2cd80 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2cd90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cda0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2cdb0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2cdc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2cdd0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2cde0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2cdf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2ce00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2ce10 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2ce20 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2ce30 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2ce40 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2ce50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2ce60 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2ce70 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2ce80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ce90 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2cea0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2ceb0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2cec0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2ced0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2cee0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2cef0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2cf00 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2cf10 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2cf20 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2cf30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2cf40 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2cf50 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2cf60 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2cf70 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2cf80 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2cf90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cfa0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2cfb0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2cfc0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2cfd0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2cfe0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2cff0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2d000 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d010 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2d020 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2d030 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2d040 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2d050 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2d060 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2d070 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2d080 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2d090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d0a0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2d0b0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2d0c0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2d0d0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2d0e0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2d0f0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2d100 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2d110 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2d120 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2d130 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2d140 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2d150 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2d160 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2d170 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2d180 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2d190 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2d1a0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2d1b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2d1c0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2d1d0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2d1e0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2d1f0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2d200 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2d210 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2d220 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2d230 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2d240 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2d250 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2d260 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2d270 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2d280 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2d290 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2d2a0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2d2b0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2d2c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2d2d0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2d2e0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2d2f0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2d300 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2d310 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2d320 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2d330 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2d340 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2d350 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2d360 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d370 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2d380 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2d390 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2d3a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d3b0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2d3c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2d3d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d3e0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2d3f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2d400 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2d410 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d420 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2d430 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2d440 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2d450 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2d460 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2d470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2d480 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
2d490 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d4a0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2d4b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2d4c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2d4d0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2d4e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2d4f0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2d500 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2d510 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2d520 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2d530 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d540 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2d550 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2d560 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2d570 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2d580 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2d590 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2d5a0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2d5b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d5c0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2d5d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d5f0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2d600 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2d610 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2d620 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2d630 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2d640 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2d650 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2d660 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2d670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d680 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2d690 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2d6a0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2d6b0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2d6c0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
2d6d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
2d6e0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
2d6f0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
2d700 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2d710 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2d720 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2d730 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
2d740 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
2d750 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2d760 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
2d770 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
2d780 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2d790 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2d7a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
2d7b0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
2d7c0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2d7d0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
2d7e0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
2d7f0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
2d800 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
2d810 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2d820 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2d830 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
2d840 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
2d850 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2d860 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2d870 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d880 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
2d890 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2d8a0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
2d8b0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
2d8c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
2d8d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d8e0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
2d8f0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
2d900 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
2d910 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
2d920 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
2d930 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
2d940 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
2d950 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
2d960 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
2d970 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
2d980 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
2d990 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
2d9a0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
2d9b0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
2d9c0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
2d9d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
2d9e0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
2d9f0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
2da00 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
2da10 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
2da20 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
2da30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2da40 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
2da50 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
2da60 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
2da70 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
2da80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2da90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2daa0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
2dab0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2dac0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
2dad0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
2dae0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
2daf0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2db00 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
2db10 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
2db20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
2db30 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
2db40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2db50 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
2db60 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
2db70 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
2db80 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
2db90 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
2dba0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
2dbb0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
2dbc0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2dbd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2dbe0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
2dbf0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
2dc00 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2dc10 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
2dc20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
2dc30 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
2dc40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2dc50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2dc60 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
2dc70 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
2dc80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2dc90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
2dca0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
2dcb0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
2dcc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2dcd0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2dce0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
2dcf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2dd00 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
2dd10 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
2dd20 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
2dd30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
2dd40 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
2dd50 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
2dd60 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
2dd70 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
2dd80 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
2dd90 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2dda0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
2ddb0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2ddc0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2ddd0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
2dde0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2ddf0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2de00 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
2de10 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
2de20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2de30 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
2de40 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
2de50 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
2de60 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
2de70 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2de80 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2de90 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2dea0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
2deb0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
2dec0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
2ded0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2dee0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
2def0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2df00 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
2df10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2df20 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
2df30 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
2df40 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
2df50 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
2df60 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2df70 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
2df80 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2df90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2dfa0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2dfb0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2dfc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dfd0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2dfe0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2dff0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2e000 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2e010 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e020 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2e030 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2e040 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
2e050 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
2e060 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
2e070 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e080 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2e090 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
2e0a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e0b0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
2e0c0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2e0d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2e0e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2e0f0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2e100 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e110 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2e120 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2e130 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2e140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2e150 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2e160 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2e170 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2e180 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
2e190 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2e1a0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
2e1b0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
2e1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
2e1d0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
2e1e0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
2e1f0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
2e200 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
2e210 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
2e220 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
2e230 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
2e240 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
2e250 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
2e260 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2e270 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
2e280 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
2e290 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
2e2a0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
2e2b0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
2e2c0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
2e2d0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
2e2e0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
2e2f0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
2e300 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
2e310 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
2e320 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
2e330 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
2e340 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
2e350 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
2e360 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
2e370 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
2e380 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2e390 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
2e3a0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
2e3b0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
2e3c0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
2e3d0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
2e3e0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2e3f0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
2e400 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
2e410 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2e420 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e430 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
2e440 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
2e450 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
2e460 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
2e470 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
2e480 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
2e490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
2e4a0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2e4b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e4c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
2e4d0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
2e4e0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
2e4f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e500 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
2e510 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2e520 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
2e530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2e540 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
2e550 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
2e560 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
2e570 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
2e580 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
2e590 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
2e5a0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
2e5b0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
2e5c0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
2e5d0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
2e5e0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
2e5f0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
2e600 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2e610 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
2e620 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2e630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e640 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
2e650 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
2e660 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
2e670 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2e680 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2e690 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
2e6a0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
2e6b0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
2e6c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e6d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
2e6e0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2e6f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
2e700 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
2e710 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
2e720 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
2e730 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
2e740 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
2e750 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
2e760 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2e770 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
2e780 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
2e790 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2e7a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
2e7b0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
2e7c0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
2e7d0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
2e7e0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
2e7f0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2e800 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
2e810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2e820 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
2e830 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
2e840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
2e850 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
2e860 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
2e870 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
2e880 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
2e890 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
2e8a0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
2e8b0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
2e8c0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
2e8d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
2e8e0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
2e8f0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
2e900 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
2e910 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
2e920 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
2e930 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
2e940 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
2e950 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
2e960 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
2e970 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
2e980 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
2e990 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
2e9a0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
2e9b0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
2e9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2e9d0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2e9e0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2e9f0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2ea00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2ea10 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2ea20 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
2ea30 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2ea40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
2ea50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
2ea60 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2ea70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2ea80 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
2ea90 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
2eaa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2eab0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
2eac0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
2ead0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
2eae0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2eaf0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
2eb00 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2eb10 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2eb20 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2eb30 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2eb40 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2eb50 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2eb60 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
2eb70 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2eb80 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2eb90 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2eba0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2ebb0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2ebc0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2ebd0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2ebe0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2ebf0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2ec00 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
2ec10 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
2ec20 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
2ec30 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
2ec40 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
2ec50 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
2ec60 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
2ec70 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
2ec80 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2ec90 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
2eca0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
2ecb0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
2ecc0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
2ecd0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
2ece0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
2ecf0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
2ed00 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
2ed10 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
2ed20 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
2ed30 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2ed40 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
2ed50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ed60 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
2ed70 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2ed80 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
2ed90 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2eda0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
2edb0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
2edc0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
2edd0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
2ede0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
2edf0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
2ee00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2ee10 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
2ee20 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
2ee30 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
2ee40 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
2ee50 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2ee60 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
2ee70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ee80 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2ee90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2eea0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2eeb0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2eec0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2eed0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2eee0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
2eef0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
2ef00 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
2ef10 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
2ef20 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
2ef30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
2ef40 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
2ef50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ef60 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
2ef70 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
2ef80 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
2ef90 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
2efa0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2efb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2efc0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
2efd0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2efe0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2eff0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2f000 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f010 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
2f020 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
2f030 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
2f040 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
2f050 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
2f060 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
2f070 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
2f080 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
2f090 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f0a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2f0b0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
2f0c0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
2f0d0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2f0e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f0f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f100 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
2f110 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
2f120 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
2f130 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
2f140 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
2f150 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
2f160 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2f170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2f180 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
2f190 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2f1a0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2f1b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f1c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f1d0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2f1e0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2f1f0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
2f200 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2f210 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f220 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2f230 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f240 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2f250 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2f260 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2f270 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2f280 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2f290 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
2f2a0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
2f2b0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
2f2c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2f2d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f2e0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
2f2f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f300 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
2f310 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
2f320 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
2f330 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
2f340 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f350 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
2f360 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f370 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
2f380 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2f390 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2f3a0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2f3b0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2f3c0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
2f3d0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
2f3e0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2f3f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f400 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f410 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f420 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2f430 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
2f440 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
2f450 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2f460 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
2f470 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2f480 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2f490 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2f4a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f4b0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2f4c0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
2f4d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f4e0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
2f4f0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2f500 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
2f510 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
2f520 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
2f530 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2f540 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
2f550 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
2f560 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f570 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2f580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f590 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
2f5a0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
2f5b0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
2f5c0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2f5d0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
2f5e0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
2f5f0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
2f600 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
2f610 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
2f620 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
2f630 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
2f640 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
2f650 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f660 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2f670 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2f680 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2f690 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2f6a0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2f6b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2f6c0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
2f6d0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
2f6e0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
2f6f0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
2f700 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2f710 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2f720 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2f730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f740 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
2f750 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2f760 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
2f770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f780 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
2f790 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
2f7a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
2f7b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
2f7c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2f7d0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2f7e0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
2f7f0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
2f800 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f810 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2f820 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2f830 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2f840 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2f850 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
2f860 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2f870 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
2f880 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f890 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
2f8a0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2f8b0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2f8c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f8d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f8e0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
2f8f0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2f900 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
2f910 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
2f920 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2f930 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
2f940 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f950 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f960 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2f970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f980 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2f990 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
2f9a0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2f9b0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2f9c0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2f9d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2f9e0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
2f9f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2fa00 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2fa10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2fa20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fa30 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
2fa40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fa50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2fa60 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2fa70 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
2fa80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fa90 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2faa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fab0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2fac0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2fad0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2fae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2faf0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fb00 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2fb10 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2fb20 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2fb30 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2fb40 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2fb50 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2fb60 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2fb70 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2fb80 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
2fb90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2fba0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2fbb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fbc0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2fbd0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2fbe0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2fbf0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2fc00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
2fc10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2fc20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fc30 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2fc40 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
2fc50 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
2fc60 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
2fc70 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2fc80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
2fc90 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2fca0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2fcb0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2fcc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fcd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fce0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fcf0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2fd00 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
2fd10 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
2fd20 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
2fd30 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
2fd40 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2fd50 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
2fd60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fd70 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
2fd80 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
2fd90 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2fda0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fdb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fdc0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fdd0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2fde0 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
2fdf0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2fe00 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
2fe10 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
2fe20 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
2fe30 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
2fe40 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
2fe50 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2fe60 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2fe70 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2fe80 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2fe90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fea0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2feb0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
2fec0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2fed0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
2fee0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
2fef0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
2ff00 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
2ff10 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
2ff20 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2ff30 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
2ff40 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2ff50 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
2ff60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
2ff70 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
2ff80 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
2ff90 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
2ffa0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
2ffb0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2ffc0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2ffd0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2ffe0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2fff0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30000 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
30010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30020 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
30030 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
30040 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
30050 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
30060 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
30070 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
30080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
30090 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
300a0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
300b0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
300c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
300d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
300e0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
300f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
30100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30110 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30120 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
30130 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
30140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30150 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
30160 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
30170 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
30180 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
30190 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
301a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
301b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
301c0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
301d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
301e0 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
301f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
30200 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
30210 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
30220 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
30230 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
30240 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
30250 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
30260 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30270 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
30280 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
30290 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
302a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
302b0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
302c0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
302d0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
302e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
302f0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
30300 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
30310 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
30320 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30330 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
30340 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
30350 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
30360 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
30370 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
30380 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30390 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
303a0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
303b0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
303c0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
303d0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
303e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
303f0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
30400 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
30410 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
30420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30430 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30440 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
30450 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
30460 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
30470 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30490 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
304a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
304b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
304c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
304d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
304e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
304f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
30500 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
30510 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
30520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30530 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
30540 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
30550 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30560 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
30570 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30580 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
30590 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
305a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
305b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
305c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
305d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
305e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
305f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30600 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
30610 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
30620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30630 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
30640 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
30650 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
30660 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
30670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30680 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
30690 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
306a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
306b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
306c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
306d0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
306e0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
306f0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
30700 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
30710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30720 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
30730 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30740 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
30750 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
30760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30770 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
30780 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
30790 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
307a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
307b0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
307c0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
307d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
307e0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
307f0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
30800 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
30810 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
30820 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
30830 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
30840 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
30850 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30860 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
30870 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
30880 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30890 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
308a0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
308b0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
308c0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
308d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
308e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
308f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
30900 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
30910 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
30920 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
30930 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30940 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
30950 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
30960 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
30970 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
30980 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
30990 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
309a0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
309b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
309c0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
309d0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
309e0 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
309f0 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
30a00 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
30a10 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
30a20 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
30a30 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
30a40 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
30a50 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
30a60 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
30a70 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
30a80 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
30a90 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
30aa0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
30ab0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
30ac0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
30ad0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
30ae0 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
30af0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
30b00 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
30b10 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
30b20 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
30b30 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
30b40 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
30b50 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
30b60 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
30b70 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
30b80 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
30b90 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
30ba0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
30bb0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
30bc0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
30bd0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
30be0 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
30bf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
30c00 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
30c10 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
30c20 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30c30 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
30c40 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
30c50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
30c60 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
30c70 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
30c80 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
30c90 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
30ca0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
30cb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30cc0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
30cd0 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
30ce0 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
30cf0 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
30d00 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
30d10 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
30d20 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
30d30 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
30d40 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
30d50 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
30d60 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
30d70 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
30d80 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
30d90 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
30da0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
30db0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
30dc0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
30dd0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
30de0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
30df0 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
30e00 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30e10 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
30e20 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
30e30 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
30e40 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
30e50 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
30e60 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
30e70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
30e80 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
30e90 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
30ea0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
30eb0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
30ec0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
30ed0 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
30ee0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
30ef0 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
30f00 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
30f10 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
30f20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
30f30 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
30f40 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
30f50 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
30f60 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
30f70 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
30f80 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
30f90 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
30fa0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
30fb0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
30fc0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
30fd0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
30fe0 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
30ff0 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
31000 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
31010 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
31020 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
31030 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
31040 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
31050 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
31060 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
31070 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
31080 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
31090 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
310a0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
310b0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
310c0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
310d0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
310e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
310f0 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
31100 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
31110 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
31120 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
31130 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
31140 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
31150 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
31160 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
31170 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
31180 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
31190 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
311a0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
311b0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
311c0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
311d0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
311e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
311f0 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
31200 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
31210 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
31220 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31230 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
31240 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
31250 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
31260 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
31270 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
31280 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
31290 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
312a0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
312b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
312c0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
312d0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
312e0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
312f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
31300 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
31310 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
31320 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
31330 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
31340 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
31350 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
31360 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
31370 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
31380 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
31390 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
313a0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
313b0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
313c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
313d0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
313e0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
313f0 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
31400 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
31410 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
31420 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
31430 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31440 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
31450 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
31460 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
31470 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
31480 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
31490 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
314a0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
314b0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
314c0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
314d0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
314e0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
314f0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31500 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
31510 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
31520 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
31530 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
31540 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
31550 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
31560 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
31570 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
31580 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
31590 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
315a0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
315b0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
315c0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
315d0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
315e0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
315f0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
31600 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31610 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
31620 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31630 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
31640 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31650 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
31660 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
31670 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31680 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31690 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
316a0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
316b0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
316c0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
316d0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
316e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
316f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
31700 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
31710 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
31720 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
31730 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
31740 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
31750 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
31760 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
31770 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
31780 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
31790 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
317a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
317b0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
317c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
317d0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
317e0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
317f0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
31800 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
31810 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
31820 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
31830 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31840 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
31850 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
31860 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
31870 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
31880 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
31890 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
318a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
318b0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
318c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
318d0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
318e0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
318f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31900 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
31910 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
31920 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
31930 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
31940 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
31950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
31960 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
31970 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
31980 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31990 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
319a0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
319b0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
319c0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
319d0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
319e0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
319f0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
31a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31a10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
31a20 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
31a30 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
31a40 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
31a50 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
31a60 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
31a70 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
31a80 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
31a90 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
31aa0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
31ab0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
31ac0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
31ad0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
31ae0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
31af0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
31b00 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
31b10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
31b20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
31b30 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
31b40 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31b50 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
31b60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31b70 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
31b80 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
31b90 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
31ba0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
31bb0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
31bc0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
31bd0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
31be0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
31bf0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
31c00 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
31c10 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
31c20 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
31c30 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
31c40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
31c50 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
31c60 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
31c70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
31c80 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
31c90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
31ca0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
31cb0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
31cc0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
31cd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31ce0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
31cf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31d00 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
31d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
31d20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31d30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
31d40 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
31d50 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
31d60 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
31d70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
31d80 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
31d90 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
31da0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
31db0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
31dc0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
31dd0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
31de0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
31df0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
31e00 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
31e10 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
31e20 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
31e30 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
31e40 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
31e50 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
31e60 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
31e70 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
31e80 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
31e90 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
31ea0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
31eb0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
31ec0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
31ed0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
31ee0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
31ef0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31f00 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
31f10 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
31f20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
31f30 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
31f40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
31f50 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
31f60 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
31f70 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
31f80 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
31f90 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
31fa0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
31fb0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
31fc0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
31fd0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
31fe0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
31ff0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
32000 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
32010 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
32020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
32030 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
32040 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
32050 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
32060 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
32070 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
32080 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
32090 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
320a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
320b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
320c0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
320d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
320e0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
320f0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
32100 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
32110 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
32120 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
32130 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
32140 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
32150 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
32160 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
32170 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
32180 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
32190 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
321a0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
321b0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
321c0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
321d0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
321e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
321f0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
32200 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
32210 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
32220 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
32230 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
32240 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
32250 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
32260 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
32270 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
32280 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
32290 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
322a0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
322b0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
322c0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
322d0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
322e0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
322f0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
32300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32310 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
32320 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
32330 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
32340 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
32350 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
32360 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
32370 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
32380 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
32390 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
323a0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
323b0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
323c0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
323d0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
323e0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
323f0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
32400 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
32410 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
32420 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
32430 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
32440 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
32450 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
32460 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
32470 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
32480 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
32490 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
324a0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
324b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
324c0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
324d0 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
324e0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
324f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
32500 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
32510 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
32520 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
32530 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
32540 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
32550 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
32560 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
32570 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
32580 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
32590 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
325a0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
325b0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
325c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
325d0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
325e0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
325f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
32600 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
32610 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
32620 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
32630 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
32640 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
32650 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
32660 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
32670 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
32680 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
32690 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
326a0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
326b0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
326c0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
326d0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
326e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
326f0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
32700 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
32710 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
32720 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
32730 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32740 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
32750 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
32760 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
32770 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
32780 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
32790 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
327a0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
327b0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
327c0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
327d0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
327e0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
327f0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
32800 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
32810 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
32820 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
32830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
32840 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
32850 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
32860 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
32870 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
32880 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
32890 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
328a0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
328b0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
328c0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
328d0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
328e0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
328f0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
32900 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
32910 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
32920 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
32930 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
32940 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
32950 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
32960 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
32970 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
32980 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
32990 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
329a0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
329b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
329c0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
329d0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
329e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
329f0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
32a00 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
32a10 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
32a20 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
32a30 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
32a40 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
32a50 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
32a60 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
32a70 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
32a80 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
32a90 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
32aa0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
32ab0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
32ac0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
32ad0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
32ae0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
32af0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
32b00 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
32b10 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
32b20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32b30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
32b40 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
32b50 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
32b60 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
32b70 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
32b80 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
32b90 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
32ba0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
32bb0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
32bc0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
32bd0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
32be0 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
32bf0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
32c00 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
32c10 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
32c20 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
32c30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
32c40 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
32c50 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
32c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
32c70 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
32c80 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
32c90 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
32ca0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
32cb0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
32cc0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
32cd0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
32ce0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
32cf0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
32d00 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
32d10 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
32d20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
32d30 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
32d40 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
32d50 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
32d60 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
32d70 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
32d80 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
32d90 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
32da0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
32db0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
32dc0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
32dd0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
32de0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
32df0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
32e00 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
32e10 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
32e20 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
32e30 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
32e40 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
32e50 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
32e60 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
32e70 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32e80 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
32e90 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
32ea0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
32eb0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
32ec0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
32ed0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
32ee0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
32ef0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
32f00 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
32f10 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
32f20 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
32f30 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
32f40 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
32f50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
32f60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
32f70 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
32f80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32f90 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
32fa0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
32fb0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
32fc0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
32fd0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
32fe0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
32ff0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
33000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
33010 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
33020 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33030 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
33040 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
33050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
33060 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
33070 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
33080 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
33090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
330a0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
330b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
330c0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
330d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
330e0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
330f0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
33100 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
33110 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
33120 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
33130 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
33140 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
33150 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
33160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33170 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
33180 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
33190 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
331a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
331b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
331c0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
331d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
331e0 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
331f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33200 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33210 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
33220 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
33230 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
33240 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
33250 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
33260 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
33270 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
33280 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
33290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
332a0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
332b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
332c0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
332d0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
332e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
332f0 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
33300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
33310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33320 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
33330 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
33340 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
33350 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
33360 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
33370 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
33380 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
33390 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
333a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
333b0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
333c0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
333d0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
333e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
333f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
33400 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
33410 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
33420 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
33430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33440 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
33450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
33460 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
33470 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
33480 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
33490 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
334a0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
334b0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
334c0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
334d0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
334e0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
334f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
33500 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
33510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33520 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
33530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33540 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
33550 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
33560 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
33570 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33580 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
33590 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
335a0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
335b0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
335c0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
335d0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
335e0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
335f0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
33600 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
33610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33620 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
33630 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
33640 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
33650 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
33660 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
33670 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
33680 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
33690 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
336a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
336b0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
336c0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
336d0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
336e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
336f0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
33700 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
33710 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
33720 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
33730 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
33740 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
33750 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
33760 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
33770 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
33780 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33790 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
337a0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
337b0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
337c0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
337d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
337e0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
337f0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
33800 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
33810 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
33820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33830 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
33840 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
33850 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
33860 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
33870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33880 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
33890 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
338a0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
338b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
338c0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
338d0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
338e0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
338f0 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
33900 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
33910 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
33920 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
33930 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
33940 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
33950 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
33960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
33970 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
33980 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
33990 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
339a0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
339b0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
339c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
339d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
339e0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
339f0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
33a00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
33a10 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
33a20 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
33a30 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
33a40 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
33a50 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
33a60 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
33a70 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
33a80 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
33a90 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
33aa0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
33ab0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
33ac0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
33ad0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
33ae0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
33af0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
33b00 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
33b10 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
33b20 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
33b30 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
33b40 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
33b50 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
33b60 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
33b70 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
33b80 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
33b90 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
33ba0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
33bb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
33bc0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
33bd0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
33be0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
33bf0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
33c00 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
33c10 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
33c20 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
33c30 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
33c40 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
33c50 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
33c60 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
33c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33c80 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
33c90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
33ca0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
33cb0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
33cc0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
33cd0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
33ce0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
33cf0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
33d00 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
33d10 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
33d20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
33d30 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
33d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33d50 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
33d60 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
33d70 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
33d80 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
33d90 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
33da0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
33db0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
33dc0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
33dd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33de0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
33df0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33e00 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
33e10 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
33e20 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
33e30 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
33e40 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
33e50 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
33e60 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
33e70 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
33e80 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
33e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33ea0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
33eb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
33ec0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
33ed0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
33ee0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
33ef0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
33f00 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
33f10 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
33f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
33f30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
33f40 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
33f50 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
33f60 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
33f70 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
33f80 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
33f90 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
33fa0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
33fb0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
33fc0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
33fd0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
33fe0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
33ff0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
34000 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
34010 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
34020 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
34030 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
34040 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
34050 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
34060 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
34070 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
34080 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
34090 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
340a0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
340b0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
340c0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
340d0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
340e0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
340f0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
34100 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
34110 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
34120 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
34130 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
34140 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
34150 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
34160 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
34170 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
34180 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
34190 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
341a0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
341b0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
341c0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
341d0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
341e0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
341f0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
34200 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
34210 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
34220 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
34230 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
34240 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
34250 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
34260 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
34270 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
34280 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
34290 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
342a0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
342b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
342c0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
342d0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
342e0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
342f0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
34300 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
34310 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
34320 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
34330 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34340 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
34350 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
34360 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
34370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34380 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
34390 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
343a0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
343b0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
343c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
343d0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
343e0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
343f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
34400 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34410 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
34420 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
34430 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
34440 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
34450 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34460 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
34470 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
34480 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
34490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
344a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
344b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
344c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
344d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
344e0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
344f0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
34500 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
34510 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
34520 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
34530 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
34540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34550 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
34560 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
34570 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
34580 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
34590 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
345a0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
345b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
345c0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
345d0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
345e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
345f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34600 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
34610 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
34620 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
34630 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
34640 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
34650 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
34660 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
34670 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
34680 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
34690 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
346a0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
346b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
346c0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
346d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
346e0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
346f0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
34700 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
34710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34720 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
34730 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
34740 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
34750 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
34760 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
34770 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
34780 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
34790 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
347a0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
347b0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
347c0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
347d0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
347e0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
347f0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
34800 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
34810 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
34820 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
34830 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
34840 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
34850 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
34860 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
34870 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
34880 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
34890 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
348a0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
348b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
348c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
348d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
348e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
348f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
34900 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
34910 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
34920 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
34930 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
34940 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
34950 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
34960 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
34970 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
34980 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
34990 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
349a0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
349b0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
349c0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
349d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
349e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
349f0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
34a00 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
34a10 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
34a20 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
34a30 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
34a40 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
34a50 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
34a60 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
34a70 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
34a80 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
34a90 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
34aa0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
34ab0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
34ac0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
34ad0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
34ae0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
34af0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
34b00 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
34b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34b20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
34b30 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
34b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34b50 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
34b60 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
34b70 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
34b80 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
34b90 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
34ba0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
34bb0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
34bc0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
34bd0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
34be0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
34bf0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
34c00 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
34c10 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
34c20 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
34c30 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
34c40 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
34c50 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
34c60 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
34c70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34c80 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
34c90 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
34ca0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
34cb0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
34cc0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
34cd0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34ce0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
34cf0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
34d00 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
34d10 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
34d20 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
34d30 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
34d40 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
34d50 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
34d60 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
34d70 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
34d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
34d90 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
34da0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
34db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
34dc0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
34dd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34de0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
34df0 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
34e00 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
34e10 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
34e20 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
34e30 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
34e40 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
34e50 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
34e60 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
34e70 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
34e80 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
34e90 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
34ea0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
34eb0 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
34ec0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
34ed0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
34ee0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
34ef0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
34f00 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
34f10 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
34f20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
34f30 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
34f40 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
34f50 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
34f60 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
34f70 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
34f80 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
34f90 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
34fa0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
34fb0 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
34fc0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
34fd0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
34fe0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
34ff0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
35000 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
35010 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
35020 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
35030 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
35040 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
35050 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35060 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
35070 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
35080 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
35090 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
350a0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
350b0 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
350c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
350d0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
350e0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
350f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
35100 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
35110 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
35120 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35130 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
35140 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
35150 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35160 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
35170 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
35180 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
35190 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
351a0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
351b0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
351c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
351d0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
351e0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
351f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35200 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
35210 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
35220 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
35230 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
35240 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
35250 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
35260 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
35270 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
35280 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
35290 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
352a0 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
352b0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
352c0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
352d0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
352e0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
352f0 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
35300 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
35310 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35320 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
35330 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
35340 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
35350 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
35360 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
35370 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
35380 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
35390 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
353a0 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
353b0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
353c0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
353d0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
353e0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
353f0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
35400 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
35410 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
35420 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
35430 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
35440 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35450 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
35460 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
35470 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
35480 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
35490 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
354a0 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
354b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
354c0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
354d0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
354e0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
354f0 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
35500 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
35510 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
35520 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
35530 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
35540 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
35550 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
35560 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35570 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
35580 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
35590 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
355a0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
355b0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
355c0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
355d0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
355e0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
355f0 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
35600 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
35610 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
35620 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
35630 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
35640 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
35650 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
35660 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
35670 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
35680 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
35690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
356a0 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
356b0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
356c0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
356d0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
356e0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
356f0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
35700 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c  f SQLite..*/.sql
35710 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
35720 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35730 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
35740 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
35750 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
35760 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
35770 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
35780 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
35790 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
357a0 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
357b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
357c0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
357d0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
357e0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
357f0 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
35800 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
35810 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
35820 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
35830 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
35840 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
35850 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
35860 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
35870 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
35880 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
35890 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
358a0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
358b0 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b  ap_limit(int N);
358c0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
358d0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
358e0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
358f0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
35900 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
35910 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
35920 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
35930 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
35940 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
35950 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
35960 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
35970 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35980 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
35990 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
359a0 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
359b0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
359c0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
359d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
359e0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
359f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
35a00 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
35a10 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
35a20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
35a30 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
35a40 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
35a50 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
35a60 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
35a70 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
35a80 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
35a90 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
35aa0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
35ab0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
35ac0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
35ad0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
35ae0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
35af0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
35b00 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
35b10 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
35b20 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
35b30 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
35b40 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
35b50 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
35b60 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
35b70 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
35b80 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
35b90 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
35ba0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
35bb0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
35bc0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
35bd0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
35be0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
35bf0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
35c00 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
35c10 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
35c20 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
35c30 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
35c40 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
35c50 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
35c60 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
35c70 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
35c80 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
35c90 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
35ca0 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
35cb0 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
35cc0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
35cd0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
35ce0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
35cf0 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
35d00 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
35d10 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
35d20 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
35d30 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
35d40 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
35d50 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
35d60 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
35d70 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
35d80 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
35d90 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
35da0 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
35db0 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
35dc0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
35dd0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
35de0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
35df0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
35e00 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
35e10 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
35e20 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
35e30 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
35e40 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
35e50 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
35e60 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
35e70 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
35e80 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
35e90 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
35ea0 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
35eb0 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
35ec0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
35ed0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
35ee0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
35ef0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
35f00 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
35f10 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
35f20 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
35f30 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
35f40 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
35f50 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
35f60 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
35f70 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
35f80 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
35f90 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
35fa0 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
35fb0 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
35fc0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
35fd0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
35fe0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
35ff0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
36000 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
36010 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
36020 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
36030 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
36040 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
36050 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
36060 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
36070 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
36080 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
36090 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
360a0 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
360b0 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
360c0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
360d0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
360e0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
360f0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
36100 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
36110 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
36120 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
36130 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
36140 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
36150 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
36160 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
36170 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
36180 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
36190 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
361a0 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
361b0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
361c0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
361d0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
361e0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
361f0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
36200 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
36210 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
36220 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
36230 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
36240 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
36250 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
36260 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
36270 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36280 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
36290 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
362a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
362b0 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
362c0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
362d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
362e0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
362f0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
36300 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
36310 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
36320 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
36330 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
36340 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
36350 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
36360 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
36370 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
36380 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
36390 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
363a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
363b0 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
363c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
363d0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
363e0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
363f0 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
36400 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36410 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
36420 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
36430 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
36440 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
36450 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
36460 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
36470 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
36480 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
36490 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
364a0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
364b0 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
364c0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
364d0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
364e0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
364f0 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
36500 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
36510 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
36520 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
36530 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
36540 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
36550 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
36560 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
36570 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
36580 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
36590 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
365a0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
365b0 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
365c0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
365d0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
365e0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
365f0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
36600 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
36610 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
36620 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
36630 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
36640 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
36650 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
36660 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36670 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
36680 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
36690 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
366a0 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
366b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
366c0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
366d0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
366e0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
366f0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
36700 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
36710 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
36720 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
36730 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
36740 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
36750 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
36760 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
36770 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
36780 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
36790 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
367a0 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
367b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
367c0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
367d0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
367e0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
367f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
36800 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
36810 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
36820 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
36830 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
36840 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
36850 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
36860 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
36870 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
36880 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
36890 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
368a0 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
368b0 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
368c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
368d0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
368e0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
368f0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
36900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
36910 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
36920 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
36930 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
36940 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
36950 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
36960 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
36970 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
36980 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
36990 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
369a0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
369b0 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
369c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
369d0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
369e0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
369f0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
36a00 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
36a10 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
36a20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
36a30 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
36a40 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
36a50 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
36a60 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
36a70 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
36a80 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
36a90 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
36aa0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
36ab0 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
36ac0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
36ad0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
36ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
36af0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
36b00 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
36b10 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
36b20 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
36b30 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
36b40 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
36b50 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
36b60 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
36b70 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
36b80 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
36b90 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
36ba0 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
36bb0 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
36bc0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
36bd0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
36be0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
36bf0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
36c00 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
36c10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
36c20 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
36c30 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
36c40 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
36c50 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
36c60 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
36c70 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
36c80 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
36c90 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
36ca0 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
36cb0 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
36cc0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
36cd0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
36ce0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
36cf0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
36d00 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
36d10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36d20 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
36d30 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
36d40 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
36d50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36d60 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
36d70 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
36d80 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
36d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
36da0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
36db0 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
36dc0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
36dd0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
36de0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
36df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
36e00 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
36e10 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
36e20 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
36e30 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
36e40 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
36e50 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
36e60 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
36e70 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
36e80 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
36e90 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
36ea0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
36eb0 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
36ec0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
36ed0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
36ee0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
36ef0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
36f00 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
36f10 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
36f20 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
36f30 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
36f40 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
36f50 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
36f60 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
36f70 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
36f80 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
36f90 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
36fa0 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
36fb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
36fc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
36fd0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
36fe0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
36ff0 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
37000 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
37010 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
37020 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
37030 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
37040 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
37050 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
37060 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
37070 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
37080 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
37090 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
370a0 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
370b0 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
370c0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
370d0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
370e0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
370f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
37100 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
37110 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
37120 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
37130 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
37140 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
37150 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
37160 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
37170 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
37180 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
37190 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
371a0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
371b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
371c0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
371d0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
371e0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
371f0 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
37200 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
37210 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
37220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
37230 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
37240 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
37250 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
37260 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
37270 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
37280 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
37290 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
372a0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
372b0 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
372c0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
372d0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
372e0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
372f0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
37300 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
37310 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
37320 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
37330 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
37340 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
37350 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
37360 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
37370 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
37380 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
37390 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
373a0 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sion()]..*/.int 
373b0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
373c0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
373d0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
373e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
373f0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
37400 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
37410 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ading.**.** ^Thi
37420 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61  s interface disa
37430 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74  bles all automat
37440 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72  ic extensions pr
37450 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69  eviously.** regi
37460 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
37470 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
37480 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  sion()]..*/.void
37490 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
374a0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
374b0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
374c0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
374d0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
374e0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
374f0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
37500 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
37510 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
37520 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
37530 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
37540 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
37550 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
37560 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
37570 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
37580 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
37590 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
375a0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
375b0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
375c0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
375d0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
375e0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
375f0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
37600 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
37610 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
37620 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
37630 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
37640 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
37650 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
37660 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
37670 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
37680 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
37690 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
376a0 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
376b0 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
376c0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
376d0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
376e0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
376f0 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
37700 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
37710 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
37720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37730 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
37740 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
37750 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
37760 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
37770 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
37780 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
37790 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
377a0 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
377b0 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
377c0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
377d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
377e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
377f0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
37800 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
37810 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
37820 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
37830 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
37840 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
37850 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
37860 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
37870 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
37880 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37890 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
378a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
378b0 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
378c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
378d0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
378e0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
378f0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
37900 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
37910 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
37920 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
37930 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
37940 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
37950 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
37960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
37970 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
37980 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
37990 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
379a0 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
379b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
379c0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
379d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
379e0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
379f0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
37a00 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
37a10 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
37a20 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
37a30 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37a40 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
37a50 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
37a60 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
37a70 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
37a80 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
37a90 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
37aa0 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
37ab0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
37ac0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
37ad0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
37ae0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
37af0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
37b00 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
37b10 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
37b20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
37b30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37b40 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
37b50 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
37b60 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
37b70 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37b80 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
37b90 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
37ba0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
37bb0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
37bc0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
37bd0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37be0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
37bf0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
37c00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
37c10 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
37c20 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
37c30 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
37c40 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
37c50 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
37c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
37c70 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
37c80 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
37c90 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
37ca0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
37cb0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
37cc0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
37cd0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
37ce0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
37cf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
37d00 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
37d10 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
37d20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
37d30 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
37d40 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
37d50 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
37d60 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
37d70 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
37d80 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
37d90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
37da0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
37db0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37dc0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
37dd0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
37de0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
37df0 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
37e00 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37e10 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
37e20 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
37e30 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
37e40 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
37e50 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
37e60 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
37e70 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
37e80 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
37e90 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
37ea0 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
37eb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
37ec0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
37ed0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
37ee0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
37ef0 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
37f00 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
37f10 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
37f20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
37f30 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68  );.  /* The meth
37f40 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
37f50 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
37f60 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20  e sqlite_module 
37f70 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20  object. Those . 
37f80 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f   ** below are fo
37f90 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  r version 2 and 
37fa0 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e  greater. */.  in
37fb0 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28  t (*xSavepoint)(
37fc0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37fd0 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  Tab, int);.  int
37fe0 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c   (*xRelease)(sql
37ff0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
38000 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
38010 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c  xRollbackTo)(sql
38020 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
38030 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  , int);.};../*.*
38040 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
38050 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
38060 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
38070 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
38080 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
38090 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
380a0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
380b0 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
380c0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
380d0 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f  sed as part.** o
380e0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
380f0 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20  able] interface 
38100 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
38110 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
38120 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
38130 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
38140 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
38150 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
38160 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
38170 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
38180 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
38190 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
381a0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
381b0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
381c0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
381d0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
381e0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
381f0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
38200 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
38210 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
38220 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
38230 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
38240 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
38250 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63  ** <blockquote>c
38260 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62  olumn OP expr</b
38270 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
38280 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
38290 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
382a0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20  ;, or &gt;=.)^  
382b0 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  ^(The particular
382c0 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
382d0 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
382e0 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67  raint[].op using
382f0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   one of the.** [
38300 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
38310 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c  STRAINT_EQ | SQL
38320 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
38330 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e  AINT_ values].)^
38340 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20  .** ^(The index 
38350 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
38360 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
38370 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
38380 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
38390 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
383a0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
383b0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
383c0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
383d0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
383e0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
383f0 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
38400 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
38410 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
38420 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
38430 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
38440 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
38450 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
38460 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
38470 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
38480 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
38490 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
384a0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
384b0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
384c0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
384d0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
384e0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
384f0 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
38500 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
38510 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
38520 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
38530 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61  use terms that a
38540 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74  re.** relevant t
38550 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
38560 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
38570 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
38580 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e  .** ^Information
38590 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
385a0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
385b0 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
385c0 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72  []..** ^Each ter
385d0 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
385e0 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
385f0 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
38600 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
38610 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65   [xBestIndex] me
38620 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
38630 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
38640 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
38650 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
38660 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
38670 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
38680 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30   ^If argvIndex>0
38690 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
386a0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
386b0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
386c0 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
386d0 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
386e0 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
386f0 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
38700 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49  ry in argv.  ^(I
38710 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
38720 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
38730 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
38740 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
38750 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
38760 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
38770 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
38780 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
38790 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
387a0 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ite.)^.**.** ^Th
387b0 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
387c0 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
387d0 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
387e0 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
387f0 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
38800 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72  .** ^[sqlite3_fr
38810 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
38820 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
38830 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e  and only if.** n
38840 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
38850 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 2