/ Hex Artifact Content
Login

Artifact d51a37c14123717dec954c848f51fd635620ba00:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
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 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
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 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **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 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5230: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5240: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5250: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5260: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5270: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5280: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5290: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
52a0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
52b0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
52c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
52d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
52e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
52f0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5300: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5310: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5320: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5340: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5350: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5360: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5370: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5390: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
53a0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
53b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
53c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
53d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
53e0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
53f0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5400: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5410: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5430: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5440: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5450: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5470: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5480: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5490: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54b0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
54c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
54d0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
54e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
54f0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5500: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5510: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5520: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5540: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5550: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5560: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5580: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5590: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
55a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
55c0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
55d0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
55e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5600: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5610: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
5620: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5630: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5640: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
5650: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
5660: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5670: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5680: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
5690: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
56a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
56c0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
56d0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
56e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5700: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
5710: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
5720: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5730: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5750: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
5760: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
5770: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5780: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57a0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
57b0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
57c0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
57d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
57e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57f0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
5800: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
5810: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5820: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5840: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
5850: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
5860: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5870: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
5880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5890: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
58a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
58b0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
58c0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
58d0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
58e0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
58f0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5900: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5910: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5920: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5930: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5940: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5950: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5960: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5970: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5980: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5990: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
59a0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
59b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
59c0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
59d0: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
59e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
59f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5a00: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5a10: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5a20: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5a30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a40: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5a50: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5a60: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5a70: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5a80: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5a90: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5aa0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5ab0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5ac0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5ad0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ae0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5af0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5b00: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5b10: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5b20: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5b30: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5b40: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5b50: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5b60: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5b70: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5b80: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5b90: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5ba0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5bb0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5bc0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5bd0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5be0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5bf0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5c00: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5c10: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
5c20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5c30: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
5c40: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5c50: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
5c60: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
5c70: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
5c80: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
5c90: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
5ca0: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
5cb0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5cc0: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
5cd0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
5ce0: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
5cf0: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
5d00: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
5d10: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
5d20: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
5d30: 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65  nchanged..*/.#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d50: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
5d60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5d70: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
5d80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5d90: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
5da0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5db0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5dc0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
5dd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5de0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
5df0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
5e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5e10: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5e20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e30: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
5e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
5e70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5e80: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5e90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ea0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
5eb0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ed0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ef0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
5f00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5f10: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
5f20: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5f30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f40: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5f70: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5f80: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
5f90: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5fa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
5fb0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
5fc0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
5ff0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6000: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6010: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6020: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6030: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6040: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6060: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6070: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6080: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6090: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
60a0: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
60b0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
60c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
60d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
60e0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
60f0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6100: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6110: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6130: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6150: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6160: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6170: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6180: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6190: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
61a0: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
61b0: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
61c0: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
61d0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
61e0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
61f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6200: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6210: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6220: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6230: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6240: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6250: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6260: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6270: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6280: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6290: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
62a0: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
62b0: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
62c0: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
62d0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
62e0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
62f0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6300: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6310: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6320: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6330: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6340: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6350: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6360: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6370: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6380: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6390: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
63a0: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
63b0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
63c0: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
63d0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
63e0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
63f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6400: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6410: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6420: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6430: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6440: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6450: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6460: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6470: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6480: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6490: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
64a0: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
64b0: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
64c0: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
64d0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
64e0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
64f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6500: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6510: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6520: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6530: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
6540: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
6550: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
6560: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
6570: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
6580: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
6590: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
65a0: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
65b0: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
65c0: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
65d0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
65e0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
65f0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6600: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6610: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6620: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6630: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
6640: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
6650: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
6660: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
6670: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
6680: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
6690: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
66b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
66c0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
66d0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
66e0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
66f0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6700: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6710: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6720: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6730: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
6740: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
6750: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6760: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6770: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6780: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6790: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
67a0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
67b0: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
67c0: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
67d0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
67e0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
67f0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6800: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6820: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6830: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
6840: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
6850: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6860: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6870: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6880: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6890: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
68a0: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
68b0: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
68c0: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
68d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
68e0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
68f0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6900: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6910: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6920: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6930: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
6940: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
6950: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6960: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6970: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6980: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6990: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
69a0: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
69b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
69c0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
69d0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
69f0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6a00: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6a10: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6a20: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6a30: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
6a40: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6a50: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6a60: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6a70: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6a80: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6a90: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6aa0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6ab0: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6ac0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6ad0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6ae0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6af0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6b00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6b10: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6b20: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6b30: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
6b40: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
6b50: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
6b60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6b70: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
6b80: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
6b90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6ba0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6bb0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6bc0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6bd0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6be0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6bf0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6c00: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6c10: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6c20: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6c30: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6c40: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6c50: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6c60: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6c70: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6c80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6c90: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6ca0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6cb0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6cc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6cd0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6ce0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6cf0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6d00: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6d10: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6d20: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6d30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6d50: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6d60: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6d70: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6d80: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6d90: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6da0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6db0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6dc0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6dd0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6de0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6df0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6e00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6e10: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6e20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6e30: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6e40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e50: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6e60: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6e70: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6e90: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6ea0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6eb0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6ec0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6ed0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6ee0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6ef0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6f00: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6f10: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6f20: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6f30: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6f40: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6f50: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6f60: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6f70: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6f80: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6f90: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6fa0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6fb0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6fc0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6fd0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6fe0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6ff0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7000: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7010: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7020: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7030: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7040: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7050: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7060: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7070: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7080: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7090: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
70a0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
70b0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
70c0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
70d0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
70e0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
70f0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7100: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7110: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7120: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7130: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7140: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7150: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7160: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7170: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7180: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7190: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
71a0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
71b0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
71c0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
71d0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
71e0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
71f0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7200: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7210: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7220: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7230: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7240: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7250: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7260: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7270: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7280: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7290: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
72a0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
72b0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
72c0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
72d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
72e0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
72f0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7300: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7310: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7320: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7330: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7340: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7350: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7360: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7370: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7380: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7390: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
73a0: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
73b0: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
73c0: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
73d0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
73e0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
73f0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7400: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7410: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7420: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7430: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7440: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7450: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7460: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7470: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7480: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7490: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
74a0: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
74b0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
74c0: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
74d0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
74e0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
74f0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7500: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7510: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7520: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7530: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7540: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7550: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7560: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
7570: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7580: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
7590: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75a0: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
75b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75c0: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
75d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
75e0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
75f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7600: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7620: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
7640: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
7650: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7660: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
7670: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
7680: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7690: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
76a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
76b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
76c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
76d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
76e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
76f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7700: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7710: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7720: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7730: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
7740: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
7750: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
7760: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
7770: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
7780: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7790: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
77a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
77b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
77c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
77d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
77e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
77f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7800: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7810: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7820: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7830: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
7840: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
7850: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
7860: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
7870: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
7880: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
7890: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
78a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
78b0: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
78c0: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
78d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
78e0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
78f0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7900: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7910: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7920: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7930: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
7940: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
7950: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
7960: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
7970: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
79a0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
79b0: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
79c0: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
79d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
79e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
79f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7a00: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7a10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7a20: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7a30: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
7a40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7a50: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
7a60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
7a70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7a80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7a90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7aa0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7ab0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7ac0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7ad0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7ae0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7af0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7b00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7b10: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7b20: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7b30: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
7b40: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
7b50: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7b60: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7b70: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
7b80: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
7b90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7ba0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7bb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7bc0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7bd0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7be0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7bf0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7c00: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7c10: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7c20: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7c30: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7c40: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7c50: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7c60: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7c70: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7c80: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7c90: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7ca0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7cb0: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7cc0: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7cd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7ce0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7cf0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7d00: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7d10: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7d20: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7d30: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7d40: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7d50: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7d60: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7d70: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7d80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d90: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7da0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7db0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7dc0: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7dd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7de0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7df0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7e00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7e20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7e30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7e40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7e50: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7e60: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7e70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7e80: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7e90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7ea0: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7eb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7ec0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7ed0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7ee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7ef0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7f00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7f10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7f20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7f30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7f40: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7f50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7f60: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7f70: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7f80: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7f90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7fa0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7fb0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7fc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7fd0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7fe0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7ff0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8000: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8010: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8020: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8030: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8040: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8050: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8060: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8070: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8080: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8090: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
80a0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
80b0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
80c0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
80d0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
80e0: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
80f0: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8100: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8110: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8120: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8130: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8140: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8150: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8160: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8170: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
8180: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
8190: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
81a0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
81b0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
81c0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
81d0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
81e0: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
81f0: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8200: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8210: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8220: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8230: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
8240: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8250: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
8260: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
8270: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
8280: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8290: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
82a0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
82b0: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
82c0: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
82d0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
82e0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
82f0: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8300: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8310: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8320: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8330: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
8340: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
8350: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
8360: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
8370: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
8380: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
8390: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
83a0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
83b0: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
83c0: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
83d0: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
83e0: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
83f0: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8400: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8410: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8420: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8430: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
8440: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8450: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
8460: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
8470: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
8480: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
8490: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
84a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
84b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
84c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
84d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
84e0: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
84f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8500: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8510: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8520: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8530: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
8540: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
8550: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
8560: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
8570: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
8580: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8590: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
85a0: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
85b0: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
85c0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
85d0: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
85e0: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
85f0: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8600: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8610: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8620: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8630: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
8640: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
8650: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
8660: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
8670: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
8680: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
8690: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
86a0: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
86b0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
86c0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
86d0: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
86e0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
86f0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8700: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8710: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8720: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8730: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
8740: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8750: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
8760: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8770: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
8780: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
8790: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
87a0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
87b0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
87c0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
87d0: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
87e0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
87f0: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
8800: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
8810: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
8820: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
8830: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
8840: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
8850: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
8860: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
8870: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
8880: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
8890: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
88a0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
88b0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
88c0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
88d0: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
88e0: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
88f0: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
8900: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8910: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
8920: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
8930: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
8940: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
8950: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
8960: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
8970: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
8980: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
8990: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
89a0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
89b0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
89c0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
89d0: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
89e0: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
89f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
8a00: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
8a10: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
8a20: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
8a30: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
8a40: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
8a50: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
8a60: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
8a70: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
8a80: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
8a90: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
8aa0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
8ab0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
8ac0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
8ad0: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
8ae0: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
8af0: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
8b00: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
8b10: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
8b20: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
8b30: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
8b40: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
8b50: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
8b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ed..**.** ^The [
8b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
8b80: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
8b90: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
8ba0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
8bb0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
8bc0: 7c 20 57 72 69 74 65 20 41 48 65 61 64 20 4c 6f  | Write AHead Lo
8bd0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
8be0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
8bf0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
8c00: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
8c10: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
8c20: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
8c30: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
8c40: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
8c50: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
8c60: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
8c70: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
8c80: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
8c90: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
8ca0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
8cb0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
8cc0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
8cd0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
8ce0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
8cf0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
8d00: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
8d10: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
8d20: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
8d30: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
8d40: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
8d50: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
8d60: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
8d70: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
8d80: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
8d90: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
8da0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
8db0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
8dc0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
8dd0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
8de0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
8df0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
8e00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8e10: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
8e20: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
8e30: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
8e40: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
8e50: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
8e60: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
8e70: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
8e80: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
8e90: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
8ea0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
8eb0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
8ec0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
8ed0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
8ee0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
8ef0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
8f00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
8f10: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
8f20: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
8f30: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8f40: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
8f50: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
8f60: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
8f70: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
8f80: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
8f90: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
8fa0: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
8fb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8fc0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
8fd0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
8fe0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8ff0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
9000: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9010: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9020: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9030: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9040: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9050: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9060: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9070: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9080: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
9090: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
90a0: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
90b0: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
90c0: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
90d0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
90e0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
90f0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
9100: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
9110: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ting..**.** ^The
9120: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
9130: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9140: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
9150: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
9160: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
9170: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
9180: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
9190: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
91a0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
91b0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
91c0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
91d0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
91e0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
91f0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
9200: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
9210: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
9220: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
9230: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9240: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
9250: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
9260: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
9270: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
9280: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
9290: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
92a0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
92b0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
92c0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
92d0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
92e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
92f0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
9300: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
9310: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
9320: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
9330: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
9340: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
9350: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9360: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
9370: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
9380: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
9390: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
93a0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
93b0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
93c0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
93d0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
93e0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
93f0: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
9400: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
9410: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
9420: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
9430: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
9440: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
9450: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
9460: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
9470: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
9480: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
9490: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
94a0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
94b0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
94c0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
94d0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 57  e only..**.** ^W
94e0: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
94f0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
9500: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
9510: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9520: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
9530: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
9540: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
9550: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
9560: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
9570: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9580: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
9590: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
95a0: 72 65 66 65 72 73 2e 20 20 5e 49 66 20 74 68 65  refers.  ^If the
95b0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
95c0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
95d0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
95e0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
95f0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
9600: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
9610: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
9620: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 74    ^However, if t
9630: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9640: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
9650: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
9660: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
9670: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
9680: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
9690: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
96a0: 64 20 74 68 65 20 70 72 61 67 6d 61 20 69 74 73  d the pragma its
96b0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
96c0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
96d0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
96e0: 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2f 0a 23   statement..*/.#
96f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9700: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
9710: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
9720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
9730: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
9740: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
9750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
9760: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
9770: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
9780: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
9790: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
97a0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
97b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
97c0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
97d0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
97e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
97f0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9800: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
9810: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
9820: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
9830: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
9840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9850: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
9860: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
9890: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
98a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
98b0: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
98c0: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
98d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
98e0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
98f0: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
9900: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9920: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
9930: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9940: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
9950: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
9960: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
9970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
9980: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9990: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
99a0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
99b0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
99c0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
99d0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
99e0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
99f0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
9a00: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
9a10: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
9a20: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
9a30: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
9a40: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
9a50: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
9a60: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
9a70: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
9a80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9a90: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
9aa0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
9ab0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
9ac0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
9ad0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
9ae0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
9af0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
9b00: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
9b10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
9b20: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
9b30: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
9b40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
9b50: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
9b60: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
9b70: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
9b80: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
9b90: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
9ba0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
9bb0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
9bc0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
9bd0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
9be0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
9bf0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
9c00: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
9c10: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
9c20: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
9c30: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
9c40: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
9c50: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
9c60: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
9c70: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
9c80: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
9c90: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
9ca0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
9cb0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
9cc0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
9cd0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
9ce0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
9cf0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
9d00: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
9d10: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
9d20: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
9d30: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
9d40: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
9d50: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
9d60: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
9d70: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
9d80: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
9d90: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
9da0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
9db0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
9dc0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
9dd0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
9de0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
9df0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
9e00: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
9e10: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
9e20: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
9e30: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
9e40: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
9e50: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
9e60: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
9e70: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
9e80: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
9e90: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
9ea0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
9eb0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
9ec0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
9ed0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
9ee0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
9ef0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
9f00: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
9f10: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
9f20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
9f30: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
9f40: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
9f50: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
9f60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9f70: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
9f80: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
9f90: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
9fa0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
9fb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
9fc0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
9fd0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
9fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
9ff0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
a000: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
a010: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
a020: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
a030: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
a040: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
a050: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
a060: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
a070: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
a080: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a090: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
a0a0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
a0b0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
a0c0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
a0d0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
a0e0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
a0f0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
a100: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
a110: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
a120: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
a130: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
a140: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
a150: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
a160: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
a170: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
a180: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
a190: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
a1a0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
a1b0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
a1c0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
a1d0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
a1e0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
a1f0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
a200: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
a210: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
a220: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
a230: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a240: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
a250: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
a260: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
a270: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
a280: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
a290: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
a2a0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
a2b0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
a2c0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
a2d0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
a2e0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
a2f0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
a300: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
a310: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
a320: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
a330: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
a340: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
a350: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
a360: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
a370: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
a380: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
a390: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
a3a0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
a3b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
a3c0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
a3d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
a3e0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
a3f0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
a400: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
a410: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
a420: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
a430: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
a440: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
a450: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
a460: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
a470: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
a480: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
a490: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
a4a0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
a4b0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a4c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
a4d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
a4e0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
a4f0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
a500: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
a510: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
a520: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
a530: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
a540: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
a550: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
a560: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
a570: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
a580: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
a590: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
a5a0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
a5b0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
a5c0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
a5d0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
a5e0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
a5f0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
a600: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
a610: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
a620: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
a630: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
a640: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
a650: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
a660: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
a670: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
a680: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
a690: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
a6a0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
a6b0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
a6c0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
a6d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
a6e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a6f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
a700: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
a710: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
a720: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
a730: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
a740: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
a750: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
a760: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
a770: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
a780: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
a790: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
a7a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
a7b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
a7c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
a7d0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
a7e0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
a7f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
a800: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
a810: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
a820: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
a830: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
a840: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
a850: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
a860: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
a870: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
a880: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
a890: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
a8a0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
a8b0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
a8c0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
a8d0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
a8e0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
a8f0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
a900: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
a910: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
a920: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
a930: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
a940: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
a950: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
a960: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
a970: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
a980: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
a990: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
a9a0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
a9b0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
a9c0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
a9d0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
a9e0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
a9f0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
aa00: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
aa10: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
aa20: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
aa30: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
aa40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
aa50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
aa60: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
aa70: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
aa80: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
aa90: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
aaa0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
aab0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
aac0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
aad0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
aae0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
aaf0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
ab00: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ab10: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
ab20: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
ab30: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
ab40: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
ab50: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
ab60: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
ab70: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
ab80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
ab90: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
aba0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
abb0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
abc0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
abd0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
abe0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
abf0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
ac00: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
ac10: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
ac20: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
ac30: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
ac40: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
ac50: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
ac60: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
ac70: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
ac80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ac90: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
aca0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
acb0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
acc0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
acd0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
ace0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
acf0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
ad00: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
ad10: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
ad20: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
ad30: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
ad40: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
ad50: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
ad60: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
ad70: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
ad80: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
ad90: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
ada0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
adb0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
adc0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
add0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
ade0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
adf0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
ae00: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
ae10: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
ae20: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
ae30: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
ae40: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
ae50: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
ae60: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
ae70: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
ae80: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
ae90: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
aea0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
aeb0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
aec0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
aed0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
aee0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
aef0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
af00: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
af10: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
af20: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
af30: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
af40: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
af50: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
af60: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
af70: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
af80: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
af90: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
afa0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
afb0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
afc0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
afd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
afe0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
aff0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
b000: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
b010: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
b020: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
b030: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
b040: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
b050: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
b060: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
b070: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
b080: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
b090: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
b0a0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
b0b0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
b0c0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
b0d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
b0e0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
b0f0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
b100: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
b110: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
b120: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
b130: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
b140: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
b150: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
b160: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
b170: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
b180: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
b190: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
b1a0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
b1b0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
b1c0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
b1d0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
b1e0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
b1f0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
b200: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
b210: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
b220: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
b230: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
b240: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
b250: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
b260: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
b270: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
b280: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
b290: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
b2a0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
b2b0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
b2c0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
b2d0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
b2e0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
b2f0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
b300: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
b310: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
b320: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
b330: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
b340: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
b350: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
b360: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
b370: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
b380: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
b390: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
b3a0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
b3b0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
b3c0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
b3d0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
b3e0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
b3f0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
b400: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
b410: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
b420: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
b430: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
b440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
b450: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
b460: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
b470: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
b480: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
b490: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
b4a0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
b4b0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
b4c0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
b4d0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
b4e0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
b4f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
b500: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
b510: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
b520: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
b530: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
b540: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
b550: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
b560: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
b570: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
b580: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
b590: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
b5a0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
b5b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
b5c0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
b5d0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
b5e0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
b5f0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
b600: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
b610: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
b620: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
b630: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
b640: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
b650: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
b660: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
b670: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
b680: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
b690: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
b6a0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
b6b0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
b6c0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
b6d0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
b6e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
b6f0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
b700: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
b710: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
b720: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
b730: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
b740: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
b750: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
b760: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
b770: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
b780: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
b790: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
b7a0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
b7b0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
b7c0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
b7d0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
b7e0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
b7f0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
b800: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
b810: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
b820: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
b830: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
b840: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
b850: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
b860: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
b870: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
b880: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
b890: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
b8a0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
b8b0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
b8c0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
b8d0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
b8e0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
b8f0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
b900: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
b910: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
b920: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
b930: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
b940: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
b950: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
b960: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
b970: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
b980: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
b990: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
b9a0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
b9b0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b9c0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
b9d0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
b9e0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
b9f0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
ba00: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
ba10: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
ba20: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
ba30: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
ba40: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
ba50: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
ba60: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
ba70: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
ba80: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
ba90: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
baa0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
bab0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
bac0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
bad0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
bae0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
baf0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
bb00: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
bb10: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
bb20: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
bb30: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
bb40: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
bb50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
bb60: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
bb70: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
bb80: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
bb90: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
bba0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
bbb0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
bbc0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
bbd0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
bbe0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
bbf0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
bc00: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
bc10: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
bc20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
bc30: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
bc40: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
bc50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
bc60: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
bc70: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
bc80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
bc90: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
bca0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
bcb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
bcc0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
bcd0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
bce0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
bcf0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
bd00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
bd10: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
bd20: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
bd30: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
bd40: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
bd50: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
bd60: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
bd70: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
bd80: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
bd90: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
bda0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
bdb0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
bdc0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
bdd0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
bde0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
bdf0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
be00: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
be10: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
be20: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
be30: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
be40: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
be50: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
be60: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
be70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
be80: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
be90: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
bea0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
beb0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
bec0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
bed0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
bee0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
bef0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
bf00: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
bf10: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
bf20: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
bf30: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
bf40: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
bf50: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
bf60: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
bf70: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
bf80: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
bf90: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
bfa0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
bfb0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
bfc0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
bfd0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
bfe0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
bff0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c000: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c010: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
c020: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
c030: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
c040: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
c050: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c060: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c070: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
c080: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
c090: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
c0a0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c0b0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
c0c0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
c0d0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
c0e0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
c0f0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
c100: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
c110: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c120: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
c130: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
c140: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
c150: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
c160: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
c170: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
c180: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
c190: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
c1a0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
c1b0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
c1c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
c1d0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
c1e0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
c1f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
c200: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
c210: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
c220: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
c230: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
c240: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
c250: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
c260: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
c270: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
c280: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
c290: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
c2a0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
c2b0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
c2c0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
c2d0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
c2e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c2f0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
c300: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
c310: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
c320: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
c330: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
c340: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
c350: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
c360: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
c370: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
c380: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
c390: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
c3a0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
c3b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c3c0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
c3d0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
c3e0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
c3f0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
c400: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
c410: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
c420: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
c430: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
c440: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
c450: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
c460: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
c470: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
c480: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
c490: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
c4a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
c4b0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
c4c0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
c4d0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
c4e0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
c4f0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
c500: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
c510: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
c520: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
c530: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
c540: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
c550: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
c560: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
c570: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
c580: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
c590: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c5a0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
c5b0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
c5c0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
c5d0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
c5e0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
c5f0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
c600: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
c610: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
c620: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
c630: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
c640: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
c650: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
c660: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
c670: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
c680: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
c690: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
c6a0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
c6b0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
c6c0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
c6d0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
c6e0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
c6f0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
c700: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
c710: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
c720: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
c730: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
c740: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
c750: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
c760: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
c770: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
c780: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
c790: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
c7a0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
c7b0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
c7c0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
c7d0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
c7e0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
c7f0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
c800: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
c810: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
c820: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
c830: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
c840: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
c850: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
c860: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
c870: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
c880: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
c890: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
c8a0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
c8b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
c8c0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
c8d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
c8e0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
c8f0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c900: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
c910: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
c920: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
c930: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
c940: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
c950: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
c960: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
c970: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
c980: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
c990: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
c9a0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
c9b0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
c9c0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
c9d0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
c9e0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
c9f0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
ca00: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
ca10: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
ca20: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
ca30: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
ca40: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
ca50: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
ca60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
ca70: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
ca80: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
ca90: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
caa0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
cab0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
cac0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
cad0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
cae0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
caf0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
cb00: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
cb10: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
cb20: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
cb30: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cb40: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
cb50: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
cb60: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
cb70: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
cb80: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
cb90: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
cba0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
cbb0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
cbc0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
cbd0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
cbe0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
cbf0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
cc00: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
cc10: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
cc20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
cc30: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
cc40: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
cc50: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
cc60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
cc70: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
cc80: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
cc90: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
cca0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
ccb0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
ccc0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
ccd0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
cce0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
ccf0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
cd00: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
cd10: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
cd20: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
cd30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cd40: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
cd50: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
cd60: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
cd70: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
cd80: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
cd90: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
cda0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
cdb0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
cdc0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
cdd0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
cde0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cdf0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
ce00: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ce10: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
ce20: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
ce30: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
ce40: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
ce50: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
ce60: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
ce70: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
ce80: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ce90: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
cea0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
ceb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
cec0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
ced0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
cee0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
cef0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
cf00: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
cf10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
cf20: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
cf30: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
cf40: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
cf50: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
cf60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cf70: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
cf80: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
cf90: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
cfa0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
cfb0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
cfc0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
cfd0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
cfe0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
cff0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
d000: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d010: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
d020: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
d030: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
d040: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
d050: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
d060: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
d070: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
d080: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d090: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
d0a0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
d0b0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
d0c0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
d0d0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
d0e0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
d0f0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
d100: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
d110: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
d120: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
d130: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
d140: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
d150: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
d160: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
d170: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
d180: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
d190: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
d1a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
d1b0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
d1c0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
d1d0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
d1e0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
d1f0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
d200: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
d210: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
d220: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
d230: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d240: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
d250: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
d260: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
d270: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d280: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
d290: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
d2a0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
d2b0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
d2c0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
d2d0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
d2e0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
d2f0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
d300: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
d310: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
d320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
d330: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
d340: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
d350: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
d360: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
d370: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
d380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d390: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
d3a0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
d3b0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
d3c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d3d0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
d3e0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
d3f0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
d400: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
d410: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
d420: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
d430: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
d440: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
d450: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
d460: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
d470: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
d480: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
d490: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d4a0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
d4b0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
d4c0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
d4d0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
d4e0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
d4f0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
d500: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d510: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
d520: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
d530: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
d540: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
d550: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
d560: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
d570: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
d580: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
d590: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
d5a0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
d5b0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
d5c0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
d5d0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
d5e0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
d5f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
d600: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
d610: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
d620: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
d630: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
d640: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
d650: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
d660: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
d670: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
d680: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
d690: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
d6a0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
d6b0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
d6c0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
d6d0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
d6e0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
d6f0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
d700: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
d710: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
d720: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
d730: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
d740: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
d750: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
d760: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
d770: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
d780: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
d790: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
d7a0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
d7b0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
d7c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
d7d0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
d7e0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
d7f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
d800: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
d810: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
d820: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
d830: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
d840: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
d850: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
d860: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d870: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
d880: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
d890: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
d8a0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
d8b0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
d8c0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
d8d0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
d8e0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
d8f0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
d900: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
d910: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
d920: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
d930: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
d940: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
d950: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
d960: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
d970: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
d980: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
d990: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
d9a0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
d9b0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
d9c0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
d9d0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
d9e0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
d9f0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
da00: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
da10: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
da20: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
da30: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
da40: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
da50: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
da60: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
da70: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
da80: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
da90: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
daa0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
dab0: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
dac0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
dad0: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
dae0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
daf0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
db00: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
db10: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
db20: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
db30: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
db40: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
db50: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
db60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
db70: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
db80: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
db90: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
dba0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
dbb0: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
dbc0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
dbd0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
dbe0: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
dbf0: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
dc00: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
dc10: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
dc20: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
dc30: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
dc40: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
dc50: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
dc60: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
dc70: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
dc80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
dc90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
dca0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
dcb0: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
dcc0: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
dcd0: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
dce0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
dcf0: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
dd00: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
dd10: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
dd20: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
dd30: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
dd40: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
dd50: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
dd60: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
dd70: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
dd80: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
dd90: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
dda0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
ddb0: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
ddc0: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
ddd0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
dde0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ddf0: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
de00: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
de10: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
de20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
de30: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
de40: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
de50: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
de60: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
de70: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
de80: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
de90: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
dea0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
deb0: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
dec0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
ded0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
dee0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
def0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
df00: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
df10: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
df20: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
df30: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
df40: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
df50: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
df60: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
df70: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
df80: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
df90: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
dfa0: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
dfb0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
dfc0: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
dfd0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
dfe0: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
dff0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
e000: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
e010: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
e020: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
e030: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
e040: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
e050: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
e060: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
e070: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
e080: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
e090: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
e0a0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
e0b0: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
e0c0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
e0d0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
e0e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e0f0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
e100: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e110: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
e120: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
e130: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
e140: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
e150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
e160: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
e170: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
e180: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e190: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
e1a0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
e1b0: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
e1c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e1d0: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
e1e0: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
e1f0: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
e200: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
e210: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
e220: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
e230: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
e240: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
e250: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
e260: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
e270: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
e280: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
e290: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
e2a0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
e2b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
e2c0: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
e2d0: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
e2e0: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
e2f0: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
e300: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
e310: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
e320: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
e330: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
e340: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
e350: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
e360: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
e370: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
e380: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
e390: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
e3a0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
e3b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
e3c0: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
e3d0: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
e3e0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
e3f0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
e400: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
e410: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
e420: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
e430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e440: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
e450: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
e460: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
e470: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
e480: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e490: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
e4a0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
e4b0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
e4c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
e4d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
e4e0: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
e4f0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e500: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
e510: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
e520: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
e530: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
e540: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
e550: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
e560: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
e570: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
e580: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
e590: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
e5a0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
e5b0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
e5c0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
e5d0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
e5e0: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
e5f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e600: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
e610: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
e620: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
e630: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
e640: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
e650: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
e660: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
e670: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
e680: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
e690: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
e6a0: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
e6b0: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
e6c0: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
e6d0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
e6e0: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
e6f0: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
e700: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
e710: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
e720: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
e730: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
e740: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
e750: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
e760: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
e770: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
e780: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
e790: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
e7a0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
e7b0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
e7c0: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
e7d0: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
e7e0: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
e7f0: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
e800: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
e810: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
e820: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
e830: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
e840: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
e850: 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
e860: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
e870: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
e880: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
e890: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
e8a0: 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
e8b0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
e8c0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
e8d0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
e8e0: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
e8f0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
e900: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
e910: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
e920: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
e930: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
e940: 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
e950: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
e960: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
e970: 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
e980: 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
e990: 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
e9a0: 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
e9b0: 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
e9c0: 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
e9d0: 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
e9e0: 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
e9f0: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
ea00: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
ea10: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
ea20: 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
ea30: 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
ea40: 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
ea50: 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
ea60: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
ea70: 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
ea80: 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
ea90: 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
eaa0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
eab0: 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
eac0: 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
ead0: 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
eae0: 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
eaf0: 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
eb00: 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
eb10: 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
eb20: 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
eb30: 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
eb40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
eb50: 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
eb60: 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
eb70: 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
eb80: 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
eb90: 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
eba0: 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
ebb0: 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
ebc0: 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
ebd0: 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
ebe0: 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
ebf0: 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
ec00: 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
ec10: 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
ec20: 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
ec30: 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65  locator.  (For e
ec40: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
ec50: 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
ec60: 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
ec70: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
ec80: 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
ec90: 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
eca0: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
ecb0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
ecc0: 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
ecd0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ece0: 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
ecf0: 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
ed00: 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
ed10: 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
ed20: 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
ed30: 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
ed40: 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
ed50: 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
ed60: 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
ed70: 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
ed80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
ed90: 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
eda0: 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
edb0: 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
edc0: 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
edd0: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
ede0: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
edf0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
ee00: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
ee10: 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
ee20: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
ee30: 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
ee40: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
ee50: 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
ee60: 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
ee70: 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
ee80: 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
ee90: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
eea0: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
eeb0: 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
eec0: 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
eed0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
eee0: 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
eef0: 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
ef00: 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
ef10: 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
ef20: 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
ef30: 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
ef40: 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
ef50: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
ef60: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ef70: 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
ef80: 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
ef90: 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
efa0: 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
efb0: 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
efc0: 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
efd0: 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
efe0: 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
eff0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
f000: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
f010: 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
f020: 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
f030: 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
f040: 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
f050: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
f060: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
f070: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
f080: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
f090: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
f0a0: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
f0b0: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
f0c0: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
f0d0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
f0e0: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
f0f0: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
f100: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
f110: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
f120: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
f130: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
f140: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
f150: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
f160: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
f170: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
f180: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
f190: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
f1a0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
f1b0: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
f1c0: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
f1d0: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
f1e0: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
f1f0: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
f200: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
f210: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
f220: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
f230: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
f240: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
f250: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
f260: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
f270: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
f280: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
f290: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
f2a0: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
f2b0: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
f2c0: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
f2d0: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
f2e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f2f0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
f300: 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
f310: 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
f320: 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
f330: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
f340: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
f350: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
f360: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
f370: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
f380: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
f390: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
f3a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
f3b0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f3c0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f3d0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f3e0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f3f0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f400: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f410: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f420: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f430: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f440: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f450: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f460: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f470: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f480: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
f490: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
f4a0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
f4b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
f4c0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
f4d0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
f4e0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
f4f0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
f500: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
f510: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
f520: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
f530: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
f540: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
f550: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
f560: 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
f570: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
f580: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
f590: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
f5a0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
f5b0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
f5c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
f5d0: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
f5e0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
f5f0: 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
f600: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
f610: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
f620: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
f630: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
f640: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
f650: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
f660: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
f670: 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
f680: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f690: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f6a0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f6b0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f6c0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f6d0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f6e0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
f6f0: 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
f700: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f710: 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
f720: 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
f730: 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
f740: 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
f750: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
f760: 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
f770: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
f780: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
f790: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
f7a0: 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
f7b0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
f7c0: 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
f7d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
f7e0: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
f7f0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
f800: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
f810: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
f820: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f830: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
f840: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
f850: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f860: 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
f870: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
f880: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
f890: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
f8a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f8b0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
f8c0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
f8d0: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
f8e0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
f8f0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
f900: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
f910: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
f920: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
f930: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
f940: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
f950: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
f960: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
f970: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
f980: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
f990: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
f9a0: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
f9b0: 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
f9c0: 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
f9d0: 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
f9e0: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
f9f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
fa00: 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
fa10: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
fa20: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
fa30: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
fa40: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
fa50: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
fa60: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
fa70: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
fa80: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
fa90: 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
faa0: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
fab0: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
fac0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
fad0: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
fae0: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
faf0: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
fb00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
fb10: 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
fb20: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
fb30: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
fb40: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
fb50: 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
fb60: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
fb70: 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
fb80: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
fb90: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
fba0: 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
fbb0: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
fbc0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
fbd0: 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
fbe0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
fbf0: 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
fc00: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
fc10: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
fc20: 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
fc30: 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
fc40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
fc50: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
fc60: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
fc70: 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
fc80: 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
fc90: 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
fca0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fcb0: 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
fcc0: 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
fcd0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
fce0: 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
fcf0: 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
fd00: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
fd10: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
fd20: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
fd30: 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
fd40: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
fd50: 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
fd60: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
fd70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
fd80: 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
fd90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
fda0: 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
fdb0: 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
fdc0: 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
fdd0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
fde0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
fdf0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
fe00: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
fe10: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
fe20: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
fe30: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
fe40: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
fe50: 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
fe60: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
fe70: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
fe80: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
fe90: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
fea0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
feb0: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
fec0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
fed0: 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
fee0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
fef0: 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
ff00: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
ff10: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ff20: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
ff30: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ff40: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ff50: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ff60: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ff70: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
ff80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
ff90: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
ffa0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
ffb0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
ffc0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
ffd0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ffe0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
fff0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10000 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
10010 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10020 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
10030 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
10040 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
10050 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
10060 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
10070 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
10080 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
10090 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
100a0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
100b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
100c0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
100d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
100e0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
100f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10100 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
10110 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10120 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10130 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10140 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10150 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10160 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10170 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10180 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10190 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
101a0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
101b0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
101c0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
101d0 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
101e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
101f0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
10200 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
10210 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
10220 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
10230 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
10240 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
10250 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
10260 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
10270 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
10280 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
10290 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
102a0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
102b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
102c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
102d0 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
102e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
102f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
10300 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10310 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10320 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
10330 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
10340 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
10350 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
10360 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
10370 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
10380 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
10390 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
103a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
103b0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
103c0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
103d0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
103e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
103f0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
10400 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
10410 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
10420 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
10430 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
10440 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
10450 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
10460 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
10470 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
10480 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
10490 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
104a0 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
104b0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
104c0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
104d0 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
104e0 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
104f0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
10500 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
10510 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
10520 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
10530 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10540 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
10550 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
10560 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
10570 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10580 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
10590 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
105a0 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
105b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
105c0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
105d0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
105e0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
105f0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
10600 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
10610 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
10620 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
10630 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
10640 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
10650 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
10660 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
10670 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
10680 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
10690 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
106a0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
106b0 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
106c0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
106d0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
106e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
106f0 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
10700 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
10710 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
10720 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10730 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
10740 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
10750 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
10760 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
10770 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
10780 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
10790 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
107a0 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
107b0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
107c0 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
107d0 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
107e0 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
107f0 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
10800 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
10810 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10820 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
10830 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
10840 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
10850 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
10860 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
10870 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
10880 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
10890 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
108a0 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
108b0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
108c0 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
108d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
108e0 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
108f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
10900 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
10910 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
10920 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
10930 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10940 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
10950 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
10960 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
10970 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10980 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
10990 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
109a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
109b0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
109c0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
109d0 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
109e0 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
109f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10a00 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
10a10 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
10a20 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
10a30 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10a40 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
10a50 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
10a60 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
10a70 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
10a80 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
10a90 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
10aa0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
10ab0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
10ac0 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
10ad0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
10ae0 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
10af0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
10b00 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
10b10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
10b20 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
10b30 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
10b40 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
10b50 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
10b60 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
10b70 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
10b80 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
10b90 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
10ba0 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
10bb0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
10bc0 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
10bd0 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
10be0 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
10bf0 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
10c00 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
10c10 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
10c20 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
10c30 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
10c40 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
10c50 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
10c60 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
10c70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
10c80 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
10c90 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
10ca0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
10cb0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
10cc0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
10cd0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
10ce0 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
10cf0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
10d00 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
10d10 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
10d20 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
10d30 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
10d40 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
10d50 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
10d60 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
10d70 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
10d80 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
10d90 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
10da0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
10db0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
10dc0 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
10dd0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
10de0 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
10df0 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
10e00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
10e10 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
10e20 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
10e30 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
10e40 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
10e50 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
10e60 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
10e70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10e80 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
10e90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10ea0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
10eb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10ec0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10ed0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10ee0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
10ef0 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
10f00 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
10f10 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
10f20 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
10f30 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
10f40 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
10f50 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
10f60 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
10f70 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
10f80 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
10f90 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
10fa0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
10fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
10fc0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
10fd0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
10fe0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
10ff0 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
11000 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
11010 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
11020 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
11030 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
11040 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
11050 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
11060 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
11070 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
11080 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
11090 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
110a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
110b0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
110c0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
110d0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
110e0 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
110f0 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
11100 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
11110 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
11120 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
11130 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
11140 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
11150 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
11160 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
11170 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
11180 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
11190 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
111a0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
111b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
111c0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
111d0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
111e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
111f0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
11200 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
11210 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
11220 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
11230 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
11240 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
11250 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
11260 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
11270 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
11280 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
11290 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
112a0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
112b0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
112c0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
112d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
112e0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
112f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11300 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
11310 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11320 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11330 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11340 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11350 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11360 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11370 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
11380 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
11390 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
113a0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
113b0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
113c0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
113d0 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
113e0 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
113f0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
11400 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
11410 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
11420 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
11430 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
11440 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
11450 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
11460 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
11470 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11480 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
11490 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114a0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
114b0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
114c0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
114d0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
114e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
114f0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
11500 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
11510 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
11520 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
11530 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
11540 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11550 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
11560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11570 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
11580 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
11590 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
115a0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
115b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
115c0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
115d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
115e0 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
115f0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11600 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11610 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11620 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11630 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11640 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11650 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
11660 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
11670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11680 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
11690 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
116a0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
116b0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
116c0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
116d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
116e0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
116f0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
11700 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
11710 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11720 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
11730 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
11740 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
11750 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
11760 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
11770 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
11780 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11790 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
117a0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
117b0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
117c0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
117d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
117e0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
117f0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
11800 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
11810 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
11820 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
11830 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11840 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
11850 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11860 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
11870 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
11880 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
11890 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
118a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
118b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
118c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
118d0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
118e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
118f0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11900 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
11910 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
11920 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
11930 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
11940 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
11950 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11960 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
11970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11980 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
11990 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
119a0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
119b0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
119c0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
119d0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
119e0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
119f0 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
11a00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11a10 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
11a20 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11a30 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
11a40 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
11a50 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
11a60 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
11a70 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
11a80 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
11a90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
11aa0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
11ab0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
11ac0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
11ad0 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
11ae0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
11af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
11b00 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
11b10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
11b20 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
11b30 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11b40 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11b50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
11b60 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
11b70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
11b80 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
11b90 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
11ba0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
11bb0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
11bc0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
11bd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
11be0 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
11bf0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
11c00 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
11c10 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
11c20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
11c30 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
11c40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11c50 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
11c60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11c70 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
11c80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11c90 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11ca0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11cb0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
11cc0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
11cd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11ce0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
11cf0 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
11d00 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
11d10 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
11d20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
11d30 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
11d40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
11d60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11d70 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
11d80 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
11d90 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
11da0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11db0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
11dc0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
11dd0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
11de0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
11df0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
11e00 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
11e10 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
11e20 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
11e30 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
11e40 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
11e50 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
11e60 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
11e70 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
11e80 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
11e90 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
11ea0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
11eb0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
11ec0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
11ed0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
11ee0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
11ef0 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
11f00 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
11f10 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
11f20 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
11f30 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
11f40 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
11f50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
11f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
11f70 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
11f80 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
11f90 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
11fa0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
11fb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
11fc0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
11fd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
11fe0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
11ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
12000 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
12010 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
12020 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
12030 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
12040 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
12050 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
12060 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
12070 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
12080 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
12090 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
120a0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
120b0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
120c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
120d0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
120e0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
120f0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
12100 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
12110 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
12120 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
12130 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12140 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
12150 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
12160 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
12170 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
12180 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
12190 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
121a0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
121b0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
121c0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
121d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
121e0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
121f0 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
12200 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
12210 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12220 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12230 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
12240 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
12250 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
12260 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
12270 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
12280 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
12290 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
122a0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
122b0 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67   If URI handling
122c0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
122d0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
122e0 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f  mes.** passed to
122f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
12300 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
12310 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
12320 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
12330 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
12340 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
12350 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
12360 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
12370 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
12380 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
12390 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
123a0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
123b0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
123c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
123d0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66  on is opened. If
123e0 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
123f0 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
12400 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
12410 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
12420 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
12430 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
12440 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
12450 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
12460 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
12470 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52  . By default, UR
12480 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
12490 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c  obally.** disabl
124a0 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20  ed. The default 
124b0 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61  value may be cha
124c0 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e  nged by compilin
124d0 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  g with the.** [S
124e0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73  QLITE_USE_URI] s
124f0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
12500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12510 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b  NFIG_PCACHE]] [[
12520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12530 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74  TPCACHE]].** <dt
12540 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12550 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45  CACHE and SQLITE
12560 5f 43 4f 4e 46 4e 49 47 5f 47 45 54 50 43 41 43  _CONFNIG_GETPCAC
12570 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
12580 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
12590 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
125a0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
125b0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
125c0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
125d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
125e0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
125f0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
12600 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
12610 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12620 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
12630 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
12640 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12650 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
12660 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
12670 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12680 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
12690 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
126a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
126b0 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
126c0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
126d0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
126e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
126f0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
12700 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
12710 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
12720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12730 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
12740 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
12750 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
12760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12770 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12780 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
12790 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
127a0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
127b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
127c0 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
127d0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
127e0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
127f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12800 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
12810 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
12820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12830 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
12840 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
12850 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
12860 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
12870 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12880 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
12890 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
128a0 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
128b0 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
128c0 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
128d0 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
128e0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
128f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12900 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
12910 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
12920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12930 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
12940 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
12950 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
12960 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
12970 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
12980 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
12990 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
129a0 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
129b0 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
129c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
129d0 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
129e0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
129f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12a00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12a10 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
12a20 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12a30 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
12a40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
12a50 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
12a60 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
12a70 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a  e_methods2* */..
12a80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12a90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
12aa0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
12ab0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
12ac0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
12ad0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
12ae0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
12af0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
12b00 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
12b10 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
12b20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
12b30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
12b40 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
12b50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
12b60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12b70 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
12b80 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
12b90 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
12ba0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
12bb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12bc0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
12bd0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
12be0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
12bf0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
12c00 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
12c10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12c20 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
12c30 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
12c40 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
12c50 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
12c60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
12c70 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
12c80 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
12c90 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12ca0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12cb0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12cc0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12cd0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12ce0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
12cf0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
12d00 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
12d10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12d20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
12d30 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
12d40 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
12d50 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
12d60 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
12d70 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
12d80 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
12d90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12da0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
12db0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
12dc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
12dd0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
12de0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
12df0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
12e00 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
12e10 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
12e20 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
12e30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
12e40 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
12e50 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
12e60 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
12e70 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
12e80 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
12e90 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
12ea0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
12eb0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
12ec0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12ed0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
12ee0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
12ef0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
12f00 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
12f10 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
12f20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
12f30 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
12f40 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
12f50 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
12f60 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12f70 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
12f80 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
12f90 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
12fa0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
12fb0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
12fc0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
12fd0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
12fe0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12ff0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
13000 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
13010 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
13020 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13030 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
13040 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
13050 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
13060 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
13070 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
13080 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
13090 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
130a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
130b0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
130c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
130d0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
130e0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
130f0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
13100 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
13110 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
13120 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
13130 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
13140 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
13150 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
13160 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
13170 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
13180 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
13190 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
131a0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
131b0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
131c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
131d0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
131e0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
131f0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
13200 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
13210 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
13220 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
13230 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
13240 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
13250 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
13260 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
13270 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
13280 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
13290 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
132a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
132b0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
132c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
132d0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
132e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
132f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
13300 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
13310 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
13320 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
13330 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
13340 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
13350 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
13360 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
13370 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
13380 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
13390 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
133a0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
133b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
133c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
133d0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
133e0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
133f0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
13400 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
13410 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
13420 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
13430 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
13440 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13450 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
13460 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
13470 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
13480 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
13490 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
134a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
134b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
134c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
134d0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
134e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
134f0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13500 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
13510 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
13520 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
13530 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
13540 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
13550 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
13560 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13570 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
13580 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
13590 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
135a0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
135b0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
135c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
135d0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
135e0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
135f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13600 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
13610 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
13620 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
13630 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
13640 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
13650 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
13660 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
13670 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
13680 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
13690 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
136a0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
136b0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
136c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
136d0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
136e0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
136f0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
13700 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
13710 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13720 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
13730 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
13740 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
13750 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
13760 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
13770 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
13780 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
13790 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
137a0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
137b0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
137c0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
137d0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
137e0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
137f0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
13800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
13810 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
13820 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
13830 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
13840 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
13850 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
13860 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
13870 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
13880 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
13890 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
138a0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
138b0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
138c0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
138d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
138e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
138f0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
13900 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
13910 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
13920 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
13930 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
13940 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
13950 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
13960 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
13970 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
13980 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
13990 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
139a0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
139b0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
139c0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
139d0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
139e0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
139f0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
13a00 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
13a10 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
13a20 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
13a30 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
13a40 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
13a50 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
13a60 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
13a70 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
13a80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
13a90 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
13aa0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
13ab0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
13ac0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
13ad0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
13ae0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
13af0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
13b00 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
13b10 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
13b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
13b30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
13b40 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20  gument.  ^As of 
13b50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
13b60 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69  .7.7, this routi
13b70 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74  nes.** records t
13b80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
13b90 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64  owid of both ord
13ba0 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64  inary tables and
13bb0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
13bc0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  ]..** ^If no suc
13bd0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
13be0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
13bf0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20  ccurred on that 
13c00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13c10 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74  ion, zero is ret
13c20 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  urned..**.** ^(I
13c30 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
13c40 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
13c50 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
13c60 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
13c70 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
13c80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
13c90 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
13ca0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
13cb0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
13cc0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
13cd0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
13ce0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
13cf0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
13d00 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
13d10 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
13d20 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
13d30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13d40 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
13d50 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
13d60 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
13d70 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
13d80 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
13d90 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
13da0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
13db0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
13dc0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
13dd0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
13de0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
13df0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
13e00 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
13e10 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
13e20 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
13e30 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
13e40 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
13e50 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
13e60 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
13e70 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
13e80 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
13e90 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
13ea0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
13eb0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
13ec0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
13ed0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
13ee0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
13ef0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
13f00 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
13f10 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
13f20 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
13f30 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
13f40 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
13f50 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
13f60 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
13f70 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
13f80 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
13f90 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
13fa0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
13fb0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
13fc0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
13fd0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
13fe0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
13ff0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
14000 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
14010 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
14020 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
14030 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
14040 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
14050 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
14060 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
14070 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
14080 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
14090 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
140a0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
140b0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
140c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
140d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
140e0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
140f0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
14100 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
14110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
14120 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
14130 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
14140 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
14150 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
14160 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
14170 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
14180 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
14190 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
141a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
141b0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
141c0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
141d0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
141e0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
141f0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
14200 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
14210 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
14220 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
14230 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
14240 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
14250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14260 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
14270 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
14280 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
14290 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
142a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
142b0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
142c0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
142d0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
142e0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
142f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
14300 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
14310 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
14320 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
14330 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
14340 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
14350 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
14360 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
14370 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
14380 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
14390 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
143a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
143b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
143c0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
143d0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
143e0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
143f0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
14400 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
14410 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
14420 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
14430 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
14440 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
14450 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
14460 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
14470 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
14480 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
14490 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
144a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
144b0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
144c0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
144d0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
144e0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
144f0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
14500 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
14510 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
14520 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
14530 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
14540 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
14550 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
14560 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
14570 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
14580 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
14590 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
145a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
145b0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
145c0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
145d0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
145e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
145f0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
14600 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
14610 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
14620 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
14630 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
14640 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
14650 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
14660 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
14670 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
14680 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
14690 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
146a0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
146b0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
146c0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
146d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
146e0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
146f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
14700 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
14710 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
14720 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
14730 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
14740 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
14750 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
14760 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
14770 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
14780 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
14790 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
147a0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
147b0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
147c0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
147d0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
147e0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
147f0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
14800 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
14810 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
14820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14830 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
14840 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
14850 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
14860 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
14870 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
14880 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
14890 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
148a0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
148b0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
148c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
148d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
148e0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
148f0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
14900 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
14910 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
14920 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
14930 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
14940 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
14950 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
14960 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
14970 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
14980 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
14990 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
149a0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
149b0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
149c0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
149d0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
149e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
149f0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
14a00 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
14a10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
14a20 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
14a30 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
14a40 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
14a50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
14a60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
14a70 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
14a80 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
14a90 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
14aa0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
14ab0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
14ac0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
14ad0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
14ae0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
14af0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
14b00 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
14b10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
14b20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14b30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
14b40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
14b50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
14b60 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
14b70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
14b80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
14b90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
14ba0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
14bb0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
14bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
14bd0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
14be0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
14bf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
14c00 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
14c10 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
14c20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
14c30 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
14c40 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
14c50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
14c60 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
14c70 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
14c80 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
14c90 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
14ca0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14cb0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
14cc0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
14cd0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
14ce0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
14cf0 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
14d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14d10 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
14d20 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
14d30 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
14d40 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
14d50 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
14d60 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
14d70 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
14d80 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
14d90 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
14da0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
14db0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
14dc0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
14dd0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
14de0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
14df0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
14e00 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
14e10 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
14e20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
14e30 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
14e40 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
14e50 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
14e60 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
14e70 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
14e80 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
14e90 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
14ea0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
14eb0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
14ec0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
14ed0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
14ee0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
14ef0 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
14f00 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
14f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
14f20 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
14f30 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
14f40 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
14f50 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
14f60 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
14f70 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
14f80 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
14f90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
14fa0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
14fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
14fc0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
14fd0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
14fe0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
14ff0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
15000 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
15010 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
15020 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
15030 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
15040 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
15050 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
15060 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
15070 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
15080 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
15090 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
150a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
150b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
150c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
150d0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
150e0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
150f0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
15100 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
15110 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
15120 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
15130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15140 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
15150 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
15160 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
15170 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
15180 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
15190 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
151a0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
151b0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
151c0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
151d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
151e0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
151f0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
15200 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
15210 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
15220 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
15230 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
15240 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
15250 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
15260 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
15270 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
15280 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
15290 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
152a0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
152b0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
152c0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
152d0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
152e0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
152f0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
15300 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
15310 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
15320 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
15330 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
15340 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
15350 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
15360 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
15370 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
15380 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
15390 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
153a0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
153b0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
153c0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
153d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
153e0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
153f0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
15400 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
15410 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
15420 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
15430 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
15440 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
15450 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
15460 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
15470 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
15480 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
15490 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
154a0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
154b0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
154c0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
154d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
154e0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
154f0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
15500 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
15510 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
15520 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
15530 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
15540 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
15550 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
15560 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
15570 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
15580 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
15590 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
155a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
155b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
155c0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
155d0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
155e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
155f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
15600 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
15610 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
15620 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
15630 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
15640 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
15650 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
15660 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
15670 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
15680 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
15690 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
156a0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
156b0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
156c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
156d0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
156e0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
156f0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
15700 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
15710 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
15720 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15730 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
15740 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
15750 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
15760 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
15770 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
15780 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15790 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
157a0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
157b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
157c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
157d0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
157e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
157f0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
15800 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
15810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15820 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
15830 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15840 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
15850 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
15860 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
15870 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
15880 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
15890 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
158a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
158b0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
158c0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
158d0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
158e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
158f0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
15900 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
15910 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
15920 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
15930 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
15940 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
15950 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
15960 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
15970 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
15980 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
15990 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
159a0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
159b0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
159c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
159d0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
159e0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
159f0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
15a00 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
15a10 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
15a20 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
15a30 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
15a40 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
15a50 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
15a60 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
15a70 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
15a80 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
15a90 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
15aa0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
15ab0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
15ac0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
15ad0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
15ae0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
15af0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
15b00 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
15b10 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
15b20 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
15b30 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
15b40 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
15b50 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
15b60 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
15b70 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
15b80 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
15b90 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
15ba0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
15bb0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
15bc0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
15bd0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
15be0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
15bf0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
15c00 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
15c10 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
15c20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15c30 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
15c40 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
15c50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
15c60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
15c70 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
15c80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
15c90 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
15ca0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
15cb0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
15cc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
15cd0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
15ce0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
15cf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
15d00 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
15d10 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
15d20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15d30 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
15d40 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
15d50 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
15d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
15d70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
15d80 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
15d90 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
15da0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
15db0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
15dc0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
15dd0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
15de0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
15df0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
15e00 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
15e10 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
15e20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
15e30 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
15e40 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
15e50 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
15e60 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
15e70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
15e80 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
15e90 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
15ea0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
15eb0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
15ec0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
15ed0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
15ee0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
15ef0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
15f00 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
15f10 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15f20 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
15f30 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
15f40 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
15f50 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
15f60 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
15f70 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
15f80 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
15f90 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
15fa0 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
15fb0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
15fc0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
15fd0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
15fe0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
15ff0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
16000 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
16010 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
16020 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
16030 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
16040 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
16050 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
16060 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16070 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
16080 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
16090 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
160a0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
160b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
160c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
160d0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
160e0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
160f0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
16100 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
16110 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16120 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
16130 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
16140 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
16150 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
16160 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
16170 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
16180 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
16190 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
161a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
161b0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
161c0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
161d0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
161e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
161f0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
16200 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
16210 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
16220 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
16230 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16240 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
16250 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
16260 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
16270 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
16280 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
16290 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
162a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
162b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
162c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
162d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
162e0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
162f0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
16300 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
16310 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
16320 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
16330 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
16340 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
16350 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
16360 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
16370 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
16380 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
16390 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
163a0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
163b0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
163c0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
163d0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
163e0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
163f0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
16400 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
16410 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
16420 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
16430 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16440 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
16450 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
16460 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
16470 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
16480 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
16490 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
164a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
164b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
164c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
164d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
164e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
164f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
16500 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
16510 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
16520 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
16530 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
16540 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
16550 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
16560 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
16570 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
16580 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
16590 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
165a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
165b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
165c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
165d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
165e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
165f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
16600 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
16610 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
16620 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
16630 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
16640 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
16650 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
16660 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
16670 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
16680 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
16690 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
166a0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
166b0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
166c0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
166d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
166e0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
166f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
16700 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
16710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
16720 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
16730 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
16740 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16750 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
16760 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
16770 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
16780 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
16790 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
167a0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
167b0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
167c0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
167d0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
167e0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
167f0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
16800 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
16810 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
16820 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
16830 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
16840 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
16850 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
16860 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
16870 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
16880 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
16890 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
168a0 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
168b0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
168c0 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
168d0 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
168e0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
168f0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
16900 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
16910 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
16920 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
16930 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
16940 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
16950 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
16960 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
16970 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
16980 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
16990 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
169a0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
169b0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
169c0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
169d0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
169e0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
169f0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
16a00 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
16a10 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
16a20 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
16a30 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
16a40 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
16a50 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
16a60 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
16a70 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
16a80 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
16a90 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
16aa0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
16ab0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
16ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16ad0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
16ae0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
16af0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
16b00 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
16b10 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
16b20 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
16b30 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
16b40 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
16b50 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
16b60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
16b70 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
16b80 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
16b90 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
16ba0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
16bb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
16bc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
16bd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
16be0 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
16bf0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
16c00 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
16c10 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
16c20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
16c30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
16c40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
16c50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
16c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
16c70 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
16c80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
16c90 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
16ca0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
16cb0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
16cc0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
16cd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
16ce0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
16cf0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
16d00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
16d10 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
16d20 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
16d30 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
16d40 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
16d50 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
16d60 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
16d70 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
16d80 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
16d90 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
16da0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
16db0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
16dc0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
16dd0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
16de0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
16df0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
16e00 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
16e10 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
16e20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
16e30 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
16e40 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
16e50 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
16e60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
16e70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
16e80 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
16e90 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
16ea0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
16eb0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
16ec0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
16ed0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
16ee0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
16ef0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
16f00 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
16f10 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
16f20 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
16f30 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
16f40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
16f50 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
16f60 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
16f70 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
16f80 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
16f90 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
16fa0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
16fb0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
16fc0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
16fd0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
16fe0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
16ff0 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
17000 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
17010 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
17020 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17030 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
17040 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
17050 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
17060 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
17070 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
17080 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
17090 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
170a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
170b0 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
170c0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
170d0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
170e0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
170f0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
17100 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
17110 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
17120 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
17130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17140 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
17150 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
17160 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
17170 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
17180 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
17190 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
171a0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
171b0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
171c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
171d0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
171e0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
171f0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
17200 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
17210 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
17220 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
17230 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
17240 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
17250 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
17260 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
17270 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
17280 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
17290 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
172a0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
172b0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
172c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
172d0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
172e0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
172f0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
17300 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
17310 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
17320 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
17330 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
17340 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
17350 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
17360 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
17370 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
17380 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
17390 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
173a0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
173b0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
173c0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
173d0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
173e0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
173f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
17400 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
17410 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
17420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
17430 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
17440 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
17450 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
17460 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
17470 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
17480 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
17490 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
174a0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
174b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
174c0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
174d0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
174e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
174f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
17500 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
17510 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
17520 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
17530 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
17540 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
17550 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
17560 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
17570 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17580 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
17590 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
175a0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
175b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
175c0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
175d0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
175e0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
175f0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
17600 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
17610 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
17620 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
17630 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
17640 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
17650 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
17660 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
17670 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
17680 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
17690 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
176a0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
176b0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
176c0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
176d0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
176e0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
176f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
17700 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
17710 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
17720 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
17730 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
17740 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
17750 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17760 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
17770 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17780 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
17790 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
177a0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
177b0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
177c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
177d0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
177e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
177f0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
17800 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17810 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
17820 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
17830 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
17840 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
17850 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
17860 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
17870 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
17880 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
17890 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
178a0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
178b0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
178c0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
178d0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
178e0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
178f0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
17900 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
17910 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
17920 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
17930 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
17940 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
17950 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
17960 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
17970 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
17980 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
17990 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
179a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
179b0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
179c0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
179d0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
179e0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
179f0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
17a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
17a10 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
17a20 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
17a30 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
17a40 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
17a50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
17a60 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
17a70 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
17a80 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
17a90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17aa0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
17ab0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
17ac0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
17ad0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
17ae0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
17af0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
17b00 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
17b10 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
17b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
17b30 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
17b40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
17b50 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
17b60 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
17b70 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
17b80 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
17b90 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
17ba0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
17bb0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
17bc0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
17bd0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
17be0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
17bf0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
17c00 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
17c10 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
17c20 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
17c30 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
17c40 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
17c50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
17c60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
17c70 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
17c80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
17c90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
17ca0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
17cb0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
17cc0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
17cd0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
17ce0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
17cf0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
17d00 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
17d10 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
17d20 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
17d30 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
17d40 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
17d50 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
17d60 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
17d70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
17d80 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
17d90 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
17da0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
17db0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
17dc0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
17dd0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
17de0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
17df0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
17e00 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
17e10 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
17e20 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
17e30 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
17e40 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
17e50 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
17e60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17e70 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
17e80 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
17e90 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
17ea0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
17eb0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
17ec0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
17ed0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
17ee0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
17ef0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
17f00 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
17f10 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
17f20 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
17f30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
17f40 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
17f50 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
17f60 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
17f70 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
17f80 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
17f90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
17fa0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
17fb0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
17fc0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
17fd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
17fe0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
17ff0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
18000 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
18010 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
18020 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
18030 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
18040 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
18050 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
18060 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
18070 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
18080 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
18090 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
180a0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
180b0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
180c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
180d0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
180e0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
180f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
18100 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
18110 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
18120 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
18130 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
18140 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
18150 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
18160 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
18170 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
18180 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
18190 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
181a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
181b0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
181c0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
181d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
181e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
181f0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
18200 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
18210 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
18220 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
18230 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18240 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
18250 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
18260 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
18270 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
18280 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
18290 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
182a0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
182b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
182c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
182d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
182e0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
182f0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
18300 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
18310 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
18320 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
18330 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
18340 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
18350 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
18360 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
18370 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
18380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
18390 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
183a0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
183b0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
183c0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
183d0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
183e0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
183f0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
18400 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
18410 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
18420 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
18430 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
18440 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
18450 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
18460 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
18470 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
18480 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
18490 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
184a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
184b0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
184c0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
184d0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
184e0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
184f0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
18500 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
18510 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
18520 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
18530 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
18540 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
18550 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
18560 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
18570 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
18580 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
18590 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
185a0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
185b0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
185c0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
185d0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
185e0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
185f0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
18600 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
18610 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
18620 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
18630 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
18640 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
18650 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
18660 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
18670 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
18680 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
18690 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
186a0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
186b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
186c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
186d0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
186e0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
186f0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
18700 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
18710 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
18720 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18730 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
18740 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
18750 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
18760 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
18770 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
18780 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
18790 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
187a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
187b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
187c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
187d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
187e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
187f0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
18800 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
18810 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
18820 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
18830 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
18840 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
18850 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
18860 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
18870 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
18880 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
18890 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
188a0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
188b0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
188c0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
188d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
188e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
188f0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
18900 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
18910 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
18920 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
18930 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
18940 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
18950 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
18960 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
18970 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
18980 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
18990 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
189a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
189b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
189c0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
189d0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
189e0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
189f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
18a00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
18a10 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
18a20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
18a30 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
18a40 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
18a50 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
18a60 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
18a70 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
18a80 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
18a90 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
18aa0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
18ab0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
18ac0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
18ad0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
18ae0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
18af0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
18b00 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
18b10 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
18b20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
18b30 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
18b40 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
18b50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
18b60 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
18b70 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
18b80 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
18b90 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
18ba0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
18bb0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
18bc0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18bd0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
18be0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
18bf0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
18c00 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
18c10 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
18c20 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
18c30 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
18c40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
18c50 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
18c60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
18c70 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
18c80 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
18c90 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
18ca0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
18cb0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
18cc0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
18cd0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
18ce0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
18cf0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
18d00 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
18d10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
18d20 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
18d30 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
18d40 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
18d50 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
18d60 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
18d70 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
18d80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
18d90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
18da0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
18db0 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
18dc0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
18dd0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
18de0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
18df0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
18e00 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
18e10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
18e20 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
18e30 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
18e40 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
18e50 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
18e60 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
18e70 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
18e80 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
18e90 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
18ea0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
18eb0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
18ec0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
18ed0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
18ee0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
18ef0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
18f00 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
18f10 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
18f20 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
18f30 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
18f40 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
18f50 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
18f60 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
18f70 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
18f80 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
18f90 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
18fa0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
18fb0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
18fc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18fd0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
18fe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
18ff0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
19000 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
19010 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
19020 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
19030 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
19040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19050 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
19060 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
19070 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
19080 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
19090 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
190a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
190b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
190c0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
190d0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
190e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
190f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
19100 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
19110 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
19120 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
19130 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
19140 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
19150 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19160 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
19170 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
19180 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
19190 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
191a0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
191b0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
191c0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
191d0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
191e0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
191f0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
19200 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
19210 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
19220 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
19230 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
19240 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
19250 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
19260 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
19270 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
19280 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
19290 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
192a0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
192b0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
192c0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
192d0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
192e0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
192f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
19300 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
19310 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
19320 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
19330 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
19340 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
19350 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
19360 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
19370 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
19380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19390 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
193a0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
193b0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
193c0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
193d0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
193e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
193f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
19400 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
19410 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
19420 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
19430 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
19440 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19450 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
19460 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
19470 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
19480 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
19490 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
194a0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
194b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
194c0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
194d0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
194e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
194f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
19500 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
19510 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
19520 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19530 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
19540 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19550 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
19560 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
19570 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
19580 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
19590 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
195a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
195b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
195c0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
195d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
195e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
195f0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
19600 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
19610 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
19620 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
19630 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
19640 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
19650 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
19660 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
19670 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
19680 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
19690 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
196a0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
196b0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
196c0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
196d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
196e0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
196f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
19700 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
19710 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
19720 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
19730 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
19740 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
19750 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19760 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
19770 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
19780 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
19790 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
197a0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
197b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
197c0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
197d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
197e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
197f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
19800 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
19810 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
19820 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
19830 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
19840 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
19850 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
19860 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
19870 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
19880 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
19890 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
198a0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
198b0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
198c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
198d0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
198e0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
198f0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
19900 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19910 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
19920 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
19930 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
19940 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
19950 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
19960 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
19970 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
19980 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
19990 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
199a0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
199b0 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
199c0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
199d0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
199e0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
199f0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
19a00 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
19a10 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
19a20 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
19a30 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
19a40 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
19a50 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
19a60 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
19a70 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
19a80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
19a90 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
19aa0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
19ab0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
19ac0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
19ad0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
19ae0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
19af0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
19b00 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
19b10 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
19b20 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
19b30 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
19b40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
19b50 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
19b60 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
19b70 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
19b80 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
19b90 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
19ba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19bb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
19bc0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
19bd0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
19be0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
19bf0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
19c00 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
19c10 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
19c20 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
19c30 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
19c40 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
19c50 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
19c60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
19c70 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
19c80 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
19c90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
19ca0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
19cb0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
19cc0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
19cd0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
19ce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19cf0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
19d00 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
19d10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
19d20 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
19d30 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
19d40 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
19d50 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
19d60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
19d70 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
19d80 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
19d90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
19da0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
19db0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
19dc0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
19dd0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
19de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
19df0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
19e00 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
19e10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
19e20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
19e30 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
19e40 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
19e50 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
19e60 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
19e70 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
19e80 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
19e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
19ea0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
19eb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19ec0 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
19ed0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
19ee0 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
19ef0 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
19f00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
19f10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
19f20 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
19f30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
19f40 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
19f50 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
19f60 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
19f70 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
19f80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
19f90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
19fa0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
19fb0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
19fc0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
19fd0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
19fe0 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
19ff0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a000 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1a010 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1a020 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1a030 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1a040 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1a050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1a060 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1a070 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1a080 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1a090 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1a0a0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1a0b0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1a0c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1a0d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1a0e0 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1a0f0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1a100 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1a110 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
1a120 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1a130 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1a140 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
1a150 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1a160 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1a170 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1a180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1a190 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1a1a0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1a1b0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1a1c0 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1a1d0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1a1e0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1a1f0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1a200 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1a210 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1a220 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1a230 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1a240 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1a250 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1a260 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1a270 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1a280 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1a290 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1a2a0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1a2b0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1a2c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1a2d0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1a2e0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1a2f0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1a300 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1a310 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1a320 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1a330 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1a340 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1a350 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1a360 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1a370 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1a380 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
1a390 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
1a3a0 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
1a3b0 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
1a3c0 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
1a3d0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1a3e0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1a3f0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
1a400 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1a410 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1a420 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1a430 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
1a440 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
1a450 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
1a460 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1a470 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1a480 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1a490 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1a4a0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1a4b0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1a4c0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1a4d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1a4e0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1a4f0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1a500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1a510 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1a520 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1a530 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1a540 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1a550 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1a560 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1a570 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1a580 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a590 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1a5a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a5b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1a5c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a5d0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1a5e0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1a5f0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1a600 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1a610 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1a620 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1a630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1a640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1a650 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1a660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1a670 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1a680 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1a690 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1a6a0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1a6b0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1a6c0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1a6d0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1a6e0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1a6f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a700 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1a710 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1a720 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1a730 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1a740 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1a750 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1a760 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1a770 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1a780 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1a790 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1a7a0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1a7b0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1a7c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1a7d0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1a7e0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1a7f0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1a800 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1a810 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1a820 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1a830 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1a840 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1a850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1a860 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1a870 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1a880 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1a890 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1a8a0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1a8b0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1a8c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a8d0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1a8e0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1a8f0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1a900 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1a910 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1a920 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1a930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1a940 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1a950 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1a960 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1a970 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1a980 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1a990 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1a9a0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1a9b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a9c0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1a9d0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1a9e0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1a9f0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1aa00 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1aa10 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1aa20 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1aa30 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1aa40 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1aa50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1aa60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1aa70 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1aa80 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1aa90 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1aaa0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1aab0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1aac0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1aad0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1aae0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1aaf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1ab00 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1ab10 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1ab20 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1ab30 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1ab40 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1ab50 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1ab60 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1ab70 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1ab80 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1ab90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1aba0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1abb0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1abc0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1abd0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1abe0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1abf0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1ac00 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1ac10 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1ac20 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ac30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1ac40 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1ac50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1ac60 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1ac70 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1ac80 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1ac90 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1aca0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1acb0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1acc0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1acd0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1ace0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1acf0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1ad00 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1ad10 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1ad20 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1ad30 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1ad40 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1ad50 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1ad60 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1ad70 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1ad80 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1ad90 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1ada0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1adb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1adc0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1add0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1ade0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1adf0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1ae00 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1ae10 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1ae20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1ae30 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1ae40 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1ae50 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1ae60 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1ae70 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1ae80 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1ae90 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1aea0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1aeb0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1aec0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1aed0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1aee0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1aef0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1af00 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1af10 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1af20 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1af30 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1af40 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1af50 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1af60 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1af70 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1af80 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1af90 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1afa0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1afb0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1afc0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1afd0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1afe0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1aff0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1b000 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1b010 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1b020 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1b030 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1b040 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1b050 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1b060 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1b070 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1b080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b090 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1b0a0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1b0b0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1b0c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1b0d0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1b0e0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1b0f0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1b100 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1b110 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1b120 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1b130 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1b140 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1b150 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1b160 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1b170 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1b180 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1b190 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1b1a0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1b1b0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1b1c0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1b1d0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1b1e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1b1f0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1b200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b210 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1b220 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1b230 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b240 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1b250 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1b260 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1b270 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1b280 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1b290 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1b2a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1b2b0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1b2c0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1b2d0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1b2e0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1b2f0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1b300 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1b310 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1b320 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1b330 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1b340 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1b350 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1b360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b370 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b380 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1b390 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1b3a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b3b0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1b3c0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1b3d0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1b3e0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1b3f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b400 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1b410 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1b420 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1b430 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1b440 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1b450 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1b460 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1b470 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1b480 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1b490 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1b4a0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1b4b0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1b4c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1b4d0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1b4e0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1b4f0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1b500 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1b510 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b520 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1b530 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1b540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1b550 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1b560 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1b570 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1b580 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1b590 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1b5a0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1b5b0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1b5c0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1b5d0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1b5e0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1b5f0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1b600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1b610 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1b620 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1b630 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1b640 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
1b650 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1b660 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1b670 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1b680 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1b690 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1b6a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1b6b0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1b6c0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1b6d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b6e0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1b6f0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1b700 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1b710 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1b720 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1b730 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1b740 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1b750 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1b760 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1b770 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1b780 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1b790 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1b7a0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1b7b0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1b7c0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1b7d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b7e0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1b7f0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1b800 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1b810 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1b820 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1b830 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1b840 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1b850 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1b860 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1b870 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1b880 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1b890 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1b8a0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1b8b0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1b8c0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1b8d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1b8e0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1b8f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1b900 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1b910 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1b920 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1b930 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1b940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1b950 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1b960 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1b970 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b980 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1b990 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1b9a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b9b0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1b9c0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1b9d0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1b9e0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1b9f0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1ba00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ba10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1ba20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1ba30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1ba40 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1ba50 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1ba60 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1ba70 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1ba80 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1ba90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1baa0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1bab0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1bac0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1bad0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1bae0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1baf0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1bb00 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1bb10 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1bb20 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1bb30 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1bb40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1bb50 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1bb60 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1bb70 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1bb80 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1bb90 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1bba0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1bbb0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1bbc0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1bbd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1bbe0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1bbf0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1bc00 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1bc10 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1bc20 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1bc30 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1bc40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1bc50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1bc60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1bc70 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1bc80 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1bc90 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1bca0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1bcb0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1bcc0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1bcd0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1bce0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1bcf0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1bd00 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1bd10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1bd20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1bd30 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1bd40 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1bd50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bd60 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1bd70 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1bd80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1bd90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1bda0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1bdb0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1bdc0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1bdd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1bde0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1bdf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1be00 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1be10 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1be20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1be30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1be40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1be50 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1be60 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1be70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1be80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1be90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1bea0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1beb0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1bec0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1bed0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1bef0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1bf00 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1bf10 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1bf20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bf30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1bf40 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1bf50 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1bf60 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1bf70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1bf80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bf90 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1bfa0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1bfb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1bfc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bfd0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1bfe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1bff0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c000 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c010 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c020 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1c030 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1c040 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1c050 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1c060 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c070 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1c080 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1c090 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c0a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c0b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c0c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1c0d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1c0e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1c0f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c100 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c110 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1c120 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1c130 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c140 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c150 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c160 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1c170 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1c180 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1c190 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c1a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c1b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1c1c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1c1d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1c1e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c1f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c200 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1c210 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1c220 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1c230 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c250 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1c260 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1c270 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1c280 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1c2a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1c2b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1c2c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1c2d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c2e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1c2f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1c300 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1c310 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1c320 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1c330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1c340 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1c350 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1c360 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1c370 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1c380 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1c390 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1c3a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1c3b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1c3c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c3d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1c3e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1c3f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1c400 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1c410 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1c420 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1c430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c440 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1c450 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1c460 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1c470 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1c480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1c490 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1c4a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c4b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c4c0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1c4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1c4e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1c4f0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1c500 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c510 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1c520 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1c530 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1c540 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1c550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c560 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1c570 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1c580 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1c590 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c5a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c5b0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1c5c0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1c5d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c5e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c5f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c600 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1c610 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1c620 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c630 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1c640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c650 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1c660 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1c670 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c680 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1c690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c6a0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1c6b0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1c6c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1c6d0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1c6e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c6f0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1c700 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1c710 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1c720 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1c730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c740 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1c750 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1c760 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1c770 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c780 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1c790 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1c7a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1c7b0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1c7c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1c7d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1c7e0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1c7f0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1c800 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1c810 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1c820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1c830 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1c840 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1c850 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1c860 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1c870 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1c880 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c890 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1c8a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c8b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1c8c0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1c8d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1c8e0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1c8f0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1c900 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1c910 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1c920 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1c930 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1c940 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1c950 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1c960 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1c970 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1c980 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1c990 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1c9a0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1c9b0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1c9c0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1c9d0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1c9e0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1c9f0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1ca00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1ca10 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1ca20 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1ca30 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1ca40 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1ca50 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1ca60 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1ca70 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1ca80 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1ca90 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1caa0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1cab0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1cac0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1cad0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1cae0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1caf0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1cb00 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1cb10 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1cb20 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1cb30 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1cb40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1cb50 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1cb60 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1cb70 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1cb80 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1cb90 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1cba0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1cbb0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1cbc0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1cbd0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1cbe0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1cbf0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1cc00 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1cc10 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1cc20 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1cc30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1cc40 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1cc50 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1cc60 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1cc70 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1cc80 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1cc90 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
1cca0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1ccb0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1ccc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1ccd0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1cce0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1ccf0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1cd00 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1cd10 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1cd20 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1cd30 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1cd40 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1cd50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1cd60 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1cd70 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1cd80 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1cd90 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1cda0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1cdb0 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1cdc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1cdd0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1cde0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1cdf0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1ce00 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1ce10 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1ce20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1ce30 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1ce40 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1ce50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ce60 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1ce70 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1ce80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1ce90 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1cea0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1ceb0 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1cec0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1ced0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1cee0 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1cef0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1cf00 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1cf10 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1cf20 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1cf30 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1cf40 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1cf50 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1cf60 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1cf70 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1cf80 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
1cf90 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
1cfa0 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  ack X..**.** ^On
1cfb0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1cfc0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1cfd0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1cfe0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1cff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d000 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1d010 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1d020 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1d030 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1d040 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1d050 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1d060 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1d070 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1d080 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1d090 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1d0a0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1d0b0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1d0c0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1d0d0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1d0e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1d0f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1d100 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1d110 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1d120 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1d130 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1d140 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1d150 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1d160 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1d170 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1d180 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1d190 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1d1a0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1d1b0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1d1c0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1d1d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1d1e0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1d1f0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1d200 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1d210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d220 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1d230 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1d240 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1d250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d260 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1d270 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1d280 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1d290 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
1d2a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1d2b0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1d2c0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1d2d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1d2e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1d2f0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1d300 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1d310 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1d320 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1d330 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1d340 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1d350 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1d360 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1d370 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1d380 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1d390 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1d3a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1d3b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1d3c0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1d3d0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1d3e0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1d3f0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1d400 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1d410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d420 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1d430 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1d440 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1d450 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1d460 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1d470 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1d480 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1d490 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1d4a0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1d4b0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1d4c0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1d4d0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1d4e0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1d4f0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1d500 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1d510 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1d520 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1d530 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1d540 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1d550 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1d560 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1d570 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1d580 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1d590 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1d5a0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1d5b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d5c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1d5d0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1d5e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1d5f0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1d600 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1d610 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1d620 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1d630 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1d640 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1d650 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1d660 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1d670 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1d680 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1d690 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1d6a0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1d6b0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1d6c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1d6d0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1d6e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1d6f0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1d700 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1d710 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1d720 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1d730 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1d740 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1d750 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1d760 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1d770 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1d780 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1d790 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1d7a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1d7b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1d7c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1d7d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1d7e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1d7f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d800 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1d810 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1d820 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1d830 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1d840 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1d850 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1d860 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1d870 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1d880 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1d890 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1d8a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1d8b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1d8c0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
1d8d0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
1d8e0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
1d8f0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
1d900 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
1d910 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
1d920 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
1d930 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1d940 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1d950 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
1d960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d970 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
1d980 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
1d990 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
1d9a0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
1d9b0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d9c0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1d9d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1d9e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1d9f0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1da00 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1da10 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1da20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1da30 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1da40 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
1da50 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1da60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
1da70 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1da80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1da90 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1daa0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1dab0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
1dac0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
1dad0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
1dae0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1daf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1db00 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
1db10 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
1db20 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
1db30 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
1db40 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1db50 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1db60 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1db70 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1db80 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1db90 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1dba0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1dbb0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1dbc0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1dbd0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1dbe0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
1dbf0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
1dc00 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
1dc10 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
1dc20 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
1dc30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1dc40 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1dc50 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
1dc60 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1dc70 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1dc80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1dc90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1dca0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1dcb0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1dcc0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
1dcd0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1dce0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
1dcf0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
1dd00 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
1dd10 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
1dd20 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
1dd30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
1dd40 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
1dd50 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1dd60 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
1dd70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1dd80 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
1dd90 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
1dda0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
1ddb0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
1ddc0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
1ddd0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
1dde0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
1ddf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1de00 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
1de10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1de20 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1de30 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
1de40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1de50 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
1de60 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
1de70 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1de80 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
1de90 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
1dea0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
1deb0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
1dec0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1ded0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
1dee0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1def0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1df00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1df10 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
1df20 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
1df30 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1df40 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
1df50 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1df60 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
1df70 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
1df80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
1df90 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1dfa0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
1dfb0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1dfc0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
1dfd0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1dfe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1dff0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
1e000 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
1e010 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
1e020 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
1e030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1e040 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1e050 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e060 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1e070 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1e080 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1e090 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1e0a0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1e0b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1e0c0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1e0d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1e0e0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1e0f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1e100 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1e110 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1e120 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1e130 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1e140 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
1e150 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1e160 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1e170 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1e180 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1e190 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1e1a0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1e1b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
1e1c0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
1e1d0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
1e1e0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
1e1f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e200 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
1e210 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1e220 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
1e230 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
1e240 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
1e250 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
1e260 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
1e270 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
1e280 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
1e290 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
1e2a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1e2b0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
1e2c0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
1e2d0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
1e2e0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
1e2f0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
1e300 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
1e310 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
1e320 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
1e330 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1e340 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1e350 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1e360 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1e370 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1e380 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1e390 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
1e3a0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1e3b0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1e3c0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1e3d0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1e3e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e3f0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1e400 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
1e410 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
1e420 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
1e430 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
1e440 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
1e450 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
1e460 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1e470 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
1e480 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1e490 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
1e4a0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
1e4b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
1e4c0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
1e4d0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
1e4e0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1e4f0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
1e500 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1e510 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
1e520 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
1e530 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
1e540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e550 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
1e560 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
1e570 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
1e580 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
1e590 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
1e5a0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
1e5b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
1e5c0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
1e5d0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
1e5e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1e5f0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
1e600 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
1e610 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
1e620 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1e630 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
1e640 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
1e650 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
1e660 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
1e670 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
1e680 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
1e690 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
1e6a0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
1e6b0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
1e6c0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1e6d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
1e6e0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
1e6f0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
1e700 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
1e710 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
1e720 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
1e730 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
1e740 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
1e750 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
1e760 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
1e770 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
1e780 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
1e790 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
1e7a0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
1e7b0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
1e7c0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
1e7d0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
1e7e0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
1e7f0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
1e800 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
1e810 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
1e820 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
1e830 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
1e840 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
1e850 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
1e860 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
1e870 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
1e880 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
1e890 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
1e8a0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
1e8b0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
1e8c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
1e8d0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
1e8e0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
1e8f0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
1e900 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
1e910 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
1e920 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
1e930 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
1e940 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
1e950 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
1e960 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
1e970 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
1e980 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
1e990 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
1e9a0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
1e9b0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
1e9c0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
1e9d0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
1e9e0 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
1e9f0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
1ea00 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
1ea10 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
1ea20 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
1ea30 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
1ea40 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
1ea50 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
1ea60 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
1ea70 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
1ea80 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1ea90 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
1eaa0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
1eab0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
1eac0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
1ead0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
1eae0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
1eaf0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
1eb00 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
1eb10 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
1eb20 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
1eb30 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
1eb40 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
1eb50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1eb60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1eb70 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
1eb80 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
1eb90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1eba0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
1ebb0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
1ebc0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
1ebd0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
1ebe0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
1ebf0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
1ec00 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
1ec10 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
1ec20 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
1ec30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ec40 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
1ec50 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
1ec60 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
1ec70 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
1ec80 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
1ec90 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
1eca0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
1ecb0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
1ecc0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
1ecd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ece0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
1ecf0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
1ed00 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
1ed10 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
1ed20 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
1ed30 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 20 6f  her "ro", "rw" o
1ed40 72 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2e 20  r.**     "rwc". 
1ed50 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
1ed60 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
1ed70 72 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 72  r value is an er
1ed80 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
1ed90 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
1eda0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
1edb0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1edc0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
1edd0 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1ede0 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
1edf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ee00 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
1ee10 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
1ee20 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
1ee30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ee40 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e  _prepare_v2(). ^
1ee50 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
1ee60 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
1ee70 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
1ee80 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1ee90 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
1eea0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
1eeb0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
1eec0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
1eed0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1eee0 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
1eef0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
1ef00 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
1ef10 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
1ef20 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
1ef30 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
1ef40 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
1ef50 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
1ef60 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
1ef70 52 45 41 54 45 2e 20 5e 49 66 20 73 71 6c 69 74  REATE. ^If sqlit
1ef80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ef90 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c 20 69 74  .**     used, it
1efa0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
1efb0 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
1efc0 66 6f 72 20 74 68 65 20 6d 6f 64 65 20 70 61 72  for the mode par
1efd0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 0a  ameter that is .
1efe0 2a 2a 20 20 20 20 20 6c 65 73 73 20 72 65 73 74  **     less rest
1eff0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
1f000 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
1f010 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
1f020 61 73 20 74 68 65 20 74 68 69 72 64 20 0a 2a 2a  as the third .**
1f030 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
1f040 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
1f050 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
1f060 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
1f070 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
1f080 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
1f090 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
1f0a0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
1f0b0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
1f0c0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1f0d0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
1f0e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1f0f0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
1f100 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
1f110 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
1f120 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
1f130 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
1f140 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
1f150 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
1f160 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
1f170 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1f180 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
1f190 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
1f1a0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
1f1b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1f1c0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
1f1d0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
1f1e0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
1f1f0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
1f200 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
1f210 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
1f220 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74 65  haviour requeste
1f230 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
1f240 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
1f250 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
1f260 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f270 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
1f280 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
1f290 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
1f2a0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
1f2b0 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
1f2c0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
1f2d0 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
1f2e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1f2f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1f300 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
1f310 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
1f320 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
1f330 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
1f340 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
1f350 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
1f360 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
1f370 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1f380 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
1f390 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
1f3a0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
1f3b0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
1f3c0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
1f3d0 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
1f3e0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
1f3f0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
1f400 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
1f410 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
1f420 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1f430 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
1f440 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1f450 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
1f460 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
1f470 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
1f480 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
1f490 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1f4a0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
1f4b0 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
1f4c0 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
1f4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1f4e0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
1f4f0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1f500 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
1f510 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
1f520 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
1f530 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1f540 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
1f550 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
1f560 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1f570 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1f580 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
1f590 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
1f5a0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
1f5b0 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
1f5c0 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
1f5d0 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
1f5e0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1f5f0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
1f600 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
1f610 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
1f620 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
1f630 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
1f640 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
1f650 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
1f660 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
1f670 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
1f680 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
1f690 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
1f6a0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
1f6b0 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
1f6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
1f6d0 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
1f6e0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
1f6f0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
1f700 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
1f710 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
1f720 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1f730 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
1f740 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
1f750 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
1f760 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
1f770 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
1f780 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
1f790 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
1f7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
1f7b0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1f7c0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1f7d0 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
1f7e0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
1f7f0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
1f800 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
1f810 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
1f820 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
1f830 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
1f840 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
1f850 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
1f860 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
1f870 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
1f880 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
1f890 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
1f8a0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
1f8b0 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
1f8c0 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
1f8d0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
1f8e0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
1f8f0 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
1f900 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
1f910 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
1f920 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
1f930 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
1f940 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
1f950 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
1f960 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
1f970 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
1f980 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
1f990 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
1f9a0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
1f9b0 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
1f9c0 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
1f9d0 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
1f9e0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
1f9f0 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
1fa00 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
1fa10 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
1fa20 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
1fa30 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
1fa40 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
1fa50 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
1fa60 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
1fa70 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
1fa80 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
1fa90 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
1faa0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
1fab0 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
1fac0 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
1fad0 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
1fae0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
1faf0 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
1fb00 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
1fb10 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
1fb20 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
1fb30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1fb40 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
1fb50 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1fb60 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1fb70 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1fb80 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1fb90 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1fba0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1fbb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1fbc0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1fbd0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1fbe0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1fbf0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1fc00 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1fc10 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1fc20 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1fc30 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1fc40 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1fc50 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1fc60 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1fc70 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1fc80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1fc90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1fca0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1fcb0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1fcc0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1fcd0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1fce0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1fcf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1fd00 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1fd10 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1fd20 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1fd30 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1fd40 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1fd50 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1fd60 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1fd70 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1fd80 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1fd90 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1fda0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1fdb0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1fdc0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1fdd0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1fde0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1fdf0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1fe00 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1fe10 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1fe20 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1fe30 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1fe40 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1fe50 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1fe60 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1fe70 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1fe80 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1fe90 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
1fea0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
1feb0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
1fec0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
1fed0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
1fee0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
1fef0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
1ff00 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
1ff10 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
1ff20 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
1ff30 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
1ff40 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
1ff50 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
1ff60 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
1ff70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
1ff80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1ff90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
1ffa0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1ffb0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
1ffc0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
1ffd0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
1ffe0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
1fff0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
20000 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20010 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
20020 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
20030 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
20040 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
20050 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
20060 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
20070 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
20080 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
20090 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
200a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
200b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
200c0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
200d0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
200e0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
200f0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
20100 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
20110 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
20120 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20130 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
20140 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
20150 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
20160 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
20170 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
20180 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
20190 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
201a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
201b0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
201c0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
201d0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
201e0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
201f0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
20200 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
20210 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
20220 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
20230 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
20240 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
20250 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
20260 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
20270 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20280 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
20290 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
202a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
202b0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
202c0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
202d0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
202e0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
202f0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
20300 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
20310 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
20320 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
20330 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
20340 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
20350 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
20360 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20370 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
20380 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
20390 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
203a0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
203b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
203c0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
203d0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
203e0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
203f0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
20400 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
20410 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
20420 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
20430 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
20440 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
20450 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
20460 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
20470 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
20480 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
20490 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
204a0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
204b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
204c0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
204d0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
204e0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
204f0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
20500 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
20510 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
20520 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
20530 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
20540 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
20550 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
20560 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
20570 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
20580 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
20590 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
205a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
205b0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
205c0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
205d0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
205e0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
205f0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
20600 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
20610 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
20620 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
20630 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
20640 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
20650 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
20660 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
20670 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
20680 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
20690 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
206a0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
206b0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
206c0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
206d0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
206e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  int sqlite3_uri_
206f0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68  boolean(const ch
20700 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74  ar *zFile, const
20710 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69   char *zParam, i
20720 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71  nt bDefault);.sq
20730 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
20740 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
20750 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
20760 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
20770 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
20780 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
20790 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
207a0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
207b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
207c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
207d0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
207e0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
207f0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
20800 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
20810 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
20820 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
20830 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
20840 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
20850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20860 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
20870 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
20880 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
20890 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
208a0 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
208b0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
208c0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
208d0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
208e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
208f0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
20900 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
20910 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
20920 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
20930 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
20940 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
20950 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
20960 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
20970 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
20980 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
20990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
209a0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
209b0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
209c0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
209d0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
209e0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
209f0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
20a00 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
20a10 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
20a20 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
20a30 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
20a40 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
20a50 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
20a60 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
20a70 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
20a80 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
20a90 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
20aa0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
20ab0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
20ac0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
20ad0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
20ae0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
20af0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
20b00 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
20b10 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
20b20 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ns.)^.**.** When
20b30 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
20b40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
20b50 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
20b60 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
20b70 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
20b80 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
20b90 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
20ba0 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
20bb0 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
20bc0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
20bd0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
20be0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
20bf0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
20c00 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
20c10 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
20c20 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
20c30 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
20c40 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
20c50 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
20c60 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
20c70 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
20c80 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
20c90 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
20ca0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
20cb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
20cc0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
20cd0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
20ce0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
20cf0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
20d00 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
20d10 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
20d20 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
20d30 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
20d40 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
20d50 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
20d60 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
20d70 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
20d80 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
20d90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
20da0 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
20db0 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
20dc0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
20dd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
20de0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
20df0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
20e00 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
20e10 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
20e20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
20e30 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
20e40 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
20e50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
20e60 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
20e70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
20e80 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
20e90 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
20ea0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
20eb0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
20ec0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
20ed0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
20ee0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
20ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
20f00 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
20f10 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
20f20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20f30 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
20f40 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
20f50 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
20f60 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
20f70 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
20f80 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
20f90 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
20fa0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
20fb0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
20fc0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
20fd0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
20fe0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
20ff0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
21000 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
21010 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
21020 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
21030 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
21040 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
21050 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
21060 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
21070 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21080 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
21090 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
210a0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
210b0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
210c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
210d0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
210e0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
210f0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
21100 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
21110 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
21120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
21130 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
21140 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
21150 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
21160 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
21170 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
21180 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
21190 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
211a0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
211b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
211c0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
211d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
211e0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
211f0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
21200 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
21210 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
21220 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
21230 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21240 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
21250 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
21260 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
21270 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
21280 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
21290 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
212a0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
212b0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
212c0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
212d0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
212e0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
212f0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
21300 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
21310 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21320 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
21330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21340 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
21350 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
21360 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
21370 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
21380 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
21390 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
213a0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
213b0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
213c0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
213d0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
213e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
213f0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
21400 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
21410 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
21420 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
21430 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
21440 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
21450 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
21460 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
21470 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
21480 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
21490 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
214a0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
214b0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
214c0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
214d0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
214e0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
214f0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
21500 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
21510 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
21520 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
21530 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
21540 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
21550 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
21560 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
21570 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
21580 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
21590 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
215a0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
215b0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
215c0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
215d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
215e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
215f0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
21600 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
21610 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
21620 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
21630 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
21640 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
21650 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
21660 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
21670 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
21680 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
21690 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
216a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
216b0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
216c0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
216d0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
216e0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
216f0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
21700 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
21710 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
21720 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
21730 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
21740 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
21750 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
21760 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
21770 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
21780 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
21790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
217a0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
217b0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
217c0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
217d0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
217e0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
217f0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
21800 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
21810 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
21820 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
21830 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
21840 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
21850 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
21860 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
21870 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
21880 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
21890 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
218a0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
218b0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
218c0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
218d0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
218e0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
218f0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
21900 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
21910 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
21920 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
21930 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21940 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
21950 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
21960 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
21970 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
21980 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
21990 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
219a0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
219b0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
219c0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
219d0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
219e0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
219f0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
21a00 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
21a10 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
21a20 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
21a30 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
21a40 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
21a50 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
21a60 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
21a70 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
21a80 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
21a90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
21aa0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
21ab0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
21ac0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
21ad0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
21ae0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
21af0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
21b00 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
21b10 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
21b20 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
21b30 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
21b40 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
21b50 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
21b60 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
21b70 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
21b80 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
21b90 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
21ba0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
21bb0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
21bc0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
21bd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
21be0 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
21bf0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
21c00 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
21c10 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
21c20 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
21c30 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
21c40 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
21c50 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21c60 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21c70 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
21c80 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
21c90 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
21ca0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
21cb0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
21cc0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
21cd0 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
21ce0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21cf0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
21d00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
21d10 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
21d20 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
21d30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
21d40 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
21d50 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
21d60 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
21d70 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
21d80 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
21d90 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
21da0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
21db0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
21dc0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
21dd0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
21df0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
21e00 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
21e10 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
21e20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
21e30 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
21e40 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
21e50 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
21e60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
21e70 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
21e80 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
21e90 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
21ea0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
21eb0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
21ec0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
21ed0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
21ee0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
21ef0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21f00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
21f10 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
21f20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
21f30 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
21f40 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
21f50 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
21f60 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
21f70 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
21f80 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
21f90 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
21fa0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
21fb0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
21fc0 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
21fd0 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
21fe0 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
21ff0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
22000 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
22010 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22020 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
22030 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
22040 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
22050 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
22060 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22070 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
22080 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
22090 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
220a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
220b0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
220c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
220d0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
220e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
220f0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
22100 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
22110 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
22120 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
22130 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
22140 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
22150 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
22160 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22170 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
22180 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
22190 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
221a0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
221b0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
221c0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
221d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
221e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
221f0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
22200 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
22210 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
22220 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
22230 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
22240 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
22250 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
22260 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
22270 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
22280 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
22290 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
222a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
222b0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
222c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
222d0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
222e0 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
222f0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
22300 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
22310 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
22320 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
22330 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
22340 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
22350 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
22360 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
22370 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
22380 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
22390 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
223a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
223b0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
223c0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
223d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
223e0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
223f0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
22400 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22410 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
22420 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
22430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22440 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
22450 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
22460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22470 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
22480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
22490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
224a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
224b0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
224c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
224d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
224e0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
224f0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
22500 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
22510 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
22520 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
22530 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
22540 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
22550 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
22560 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
22570 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
22580 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
22590 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
225a0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
225b0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
225c0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
225d0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
225e0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
225f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
22600 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
22610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22620 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
22630 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
22640 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
22650 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
22660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
22670 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
22680 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
22690 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
226a0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
226b0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
226c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
226d0 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
226e0 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
226f0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
22700 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
22710 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
22720 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
22730 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22740 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
22750 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
22760 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
22770 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
22780 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
22790 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
227a0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
227b0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
227c0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
227d0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
227e0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
227f0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
22800 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
22810 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
22820 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
22830 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
22840 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
22850 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
22860 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
22870 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
22880 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
22890 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
228a0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
228b0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
228c0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
228d0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
228e0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
228f0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
22900 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
22910 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
22920 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
22930 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
22940 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
22950 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
22960 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
22970 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
22980 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
22990 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
229a0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
229b0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
229c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
229d0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
229e0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
229f0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
22a00 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
22a10 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
22a20 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
22a30 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
22a40 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
22a50 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
22a60 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
22a70 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
22a80 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
22a90 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
22aa0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
22ab0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
22ac0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
22ad0 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
22ae0 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
22af0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
22b00 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
22b10 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
22b20 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
22b30 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
22b40 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
22b50 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
22b60 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
22b70 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
22b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22b90 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
22ba0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
22bb0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
22bc0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
22bd0 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
22be0 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
22bf0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
22c00 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
22c10 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
22c20 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
22c30 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
22c40 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
22c50 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
22c60 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
22c70 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
22c80 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
22c90 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
22ca0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
22cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
22cc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
22cd0 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
22ce0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
22cf0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
22d00 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
22d10 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
22d20 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
22d30 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
22d40 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
22d50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
22d60 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
22d70 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
22d80 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
22d90 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
22da0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
22db0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22dc0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
22dd0 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
22de0 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
22df0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
22e00 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
22e10 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
22e20 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
22e30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
22e40 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
22e50 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
22e60 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
22e70 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
22e80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22e90 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
22ea0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
22eb0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
22ec0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
22ed0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
22ee0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
22ef0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
22f00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
22f10 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
22f20 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
22f30 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
22f40 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
22f50 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
22f60 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
22f70 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
22f80 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
22f90 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
22fa0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
22fb0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
22fc0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
22fd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
22fe0 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
22ff0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
23000 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
23010 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
23020 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
23030 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
23040 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
23050 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
23060 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
23070 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
23080 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
23090 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
230a0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
230b0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
230c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
230d0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
230e0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
230f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
23100 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
23110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
23120 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
23130 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
23140 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
23150 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
23160 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
23170 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
23180 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
23190 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
231a0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
231b0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
231c0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
231d0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
231e0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
231f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
23200 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
23210 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
23220 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
23230 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
23240 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
23250 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
23260 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
23270 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
23280 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
23290 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
232a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
232b0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
232c0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
232d0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
232e0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
232f0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
23300 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
23310 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
23320 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
23330 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
23340 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
23350 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
23360 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
23370 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
23380 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
23390 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
233a0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
233b0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
233c0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
233d0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
233e0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
233f0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
23400 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
23410 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
23420 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
23430 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
23440 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
23450 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
23460 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
23470 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
23480 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
23490 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
234a0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
234b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
234c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
234d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
234e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
234f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23500 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
23510 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
23520 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
23530 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
23540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
23550 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
23560 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
23570 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
23580 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
23590 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
235a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
235b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
235c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
235d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
235e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
235f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
23600 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
23610 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
23620 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
23630 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23640 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
23650 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
23660 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
23670 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
23680 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
23690 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
236a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
236b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
236c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
236d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
236e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
236f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
23700 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
23710 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
23720 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
23730 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
23740 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
23750 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
23760 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
23770 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
23780 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
23790 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
237a0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
237b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
237c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
237d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
237e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
237f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
23800 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
23810 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
23820 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
23830 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
23840 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
23850 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
23860 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
23870 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
23880 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
23890 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
238a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
238b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
238c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
238d0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
238e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
238f0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
23900 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
23910 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
23920 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
23930 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
23940 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
23950 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
23960 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
23970 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
23980 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
23990 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
239a0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
239b0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
239c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
239d0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
239e0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
239f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
23a00 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
23a10 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
23a20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
23a30 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
23a40 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
23a50 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
23a60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
23a70 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
23a80 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
23a90 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
23aa0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
23ac0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
23ad0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
23ae0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
23af0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
23b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23b10 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
23b20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
23b30 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
23b40 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
23b50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
23b60 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
23b70 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
23b80 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
23b90 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
23ba0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23bb0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
23bc0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
23bd0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
23be0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
23bf0 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
23c00 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
23c10 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
23c20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
23c30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
23c40 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
23c50 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
23c60 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
23c70 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
23c80 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
23c90 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
23ca0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
23cb0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
23cc0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
23cd0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
23ce0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
23cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
23d00 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
23d10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
23d20 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
23d30 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
23d40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
23d50 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
23d60 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
23d70 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
23d80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
23d90 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
23da0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
23db0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
23dc0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
23dd0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
23de0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
23df0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
23e00 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
23e10 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
23e20 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
23e30 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
23e40 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
23e50 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
23e60 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
23e70 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
23e80 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
23e90 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
23ea0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
23eb0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
23ec0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
23ed0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
23ee0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
23ef0 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
23f00 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
23f10 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
23f20 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
23f30 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
23f40 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
23f50 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
23f60 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
23f70 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
23f80 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
23f90 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
23fa0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
23fb0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
23fc0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
23fd0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
23fe0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
23ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24000 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
24010 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
24020 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
24030 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
24040 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
24050 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
24060 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
24070 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24090 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
240a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
240b0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
240c0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
240d0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
240e0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
240f0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
24100 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
24110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24120 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
24130 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
24140 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
24150 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
24160 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
24170 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
24180 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
24190 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
241a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
241b0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
241c0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
241d0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
241e0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
241f0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
24200 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
24210 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
24220 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
24230 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
24240 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
24250 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
24260 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
24270 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
24280 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
24290 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
242a0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
242b0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
242c0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
242d0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
242e0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
242f0 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
24300 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
24310 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
24320 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
24330 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
24340 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
24350 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
24360 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
24370 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
24380 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
24390 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
243a0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
243b0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
243c0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
243d0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
243e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
243f0 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
24400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24410 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
24420 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
24430 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
24440 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
24450 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
24460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24470 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
24480 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
24490 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
244a0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
244b0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
244c0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
244d0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
244e0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
244f0 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
24500 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
24510 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
24520 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
24530 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24540 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
24550 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
24560 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
24570 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
24580 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
24590 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
245a0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
245b0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
245c0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
245d0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
245e0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
245f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
24600 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
24610 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
24620 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
24630 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
24640 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
24650 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
24660 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
24670 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
24680 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
24690 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
246a0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
246b0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
246c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
246d0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
246e0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
246f0 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
24700 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
24710 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
24720 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
24730 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
24740 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
24750 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
24760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
24770 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
24780 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
24790 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
247a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
247b0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
247c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
247d0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
247e0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
247f0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
24800 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
24810 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
24820 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
24830 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
24840 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
24850 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
24860 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
24870 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
24880 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
24890 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
248a0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
248b0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
248c0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
248d0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
248e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
248f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
24900 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
24910 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
24920 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
24930 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
24940 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
24950 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
24960 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
24970 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
24980 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
24990 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
249a0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
249b0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
249c0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
249d0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
249e0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
249f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24a00 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
24a10 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
24a20 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
24a30 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
24a40 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
24a50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
24a60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
24a70 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
24a80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
24a90 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
24aa0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
24ab0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
24ac0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
24ad0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
24ae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
24af0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
24b00 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
24b10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
24b20 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
24b30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
24b40 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
24b50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
24b60 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
24b70 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
24b80 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
24b90 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
24ba0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24bb0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
24bc0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
24bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
24be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24bf0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
24c00 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
24c10 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
24c20 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
24c30 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
24c40 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
24c50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
24c60 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
24c70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
24c80 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
24c90 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
24ca0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
24cb0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
24cc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
24cd0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
24ce0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24cf0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
24d00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
24d10 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
24d20 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
24d30 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
24d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
24d50 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
24d60 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
24d70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
24d80 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
24d90 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
24da0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
24db0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
24dc0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
24dd0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
24de0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
24df0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
24e00 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24e10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
24e20 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
24e30 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
24e40 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
24e50 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
24e60 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
24e70 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
24e80 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
24e90 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
24ea0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
24eb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
24ec0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
24ed0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
24ee0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
24ef0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
24f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
24f10 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
24f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24f30 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
24f40 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
24f50 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
24f60 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
24f70 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
24f80 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
24f90 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
24fa0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
24fb0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
24fc0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
24fd0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
24fe0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
24ff0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
25000 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
25010 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
25020 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
25030 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
25040 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
25050 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
25060 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
25070 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
25080 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
25090 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
250a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
250b0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
250c0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
250d0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
250e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
250f0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
25100 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
25110 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
25120 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
25130 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
25140 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
25150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
25160 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
25170 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
25180 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
25190 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
251a0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
251b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
251c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
251d0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
251e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
251f0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
25200 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
25210 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
25220 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
25230 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
25240 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
25250 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
25260 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
25270 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
25280 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
25290 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
252a0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
252b0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
252c0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
252d0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
252e0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
252f0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
25300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25310 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
25320 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
25330 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
25340 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
25350 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
25360 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
25370 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
25380 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
25390 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
253a0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
253b0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
253c0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
253d0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
253e0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
253f0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
25400 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
25410 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
25420 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
25430 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
25440 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
25450 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
25460 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
25470 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
25480 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
25490 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
254a0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
254b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
254c0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
254d0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
254e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
254f0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
25500 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
25510 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
25520 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
25530 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
25540 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
25550 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
25560 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
25570 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61  minator..** If a
25580 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
25590 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
255a0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
255b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
255c0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
255d0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
255e0 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
255f0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
25600 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
25610 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
25620 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
25630 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
25640 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
25650 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
25660 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
25670 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
25680 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
25690 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
256a0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
256b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
256c0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
256d0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
256e0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
256f0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
25700 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
25710 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
25720 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
25730 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
25740 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
25750 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
25760 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
25770 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
25780 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
25790 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
257a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
257b0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
257c0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
257d0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
257e0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
257f0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
25800 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
25810 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
25820 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
25830 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
25840 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
25850 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
25860 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
25870 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
25880 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
25890 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
258a0 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
258b0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
258c0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
258d0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
258e0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
258f0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
25900 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
25910 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
25920 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
25930 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
25940 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
25950 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
25960 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
25970 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
25980 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
25990 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
259a0 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
259b0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
259c0 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
259d0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
259e0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
259f0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
25a00 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
25a10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25a20 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
25a30 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
25a40 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
25a50 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
25a60 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
25a70 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
25a80 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
25a90 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
25aa0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
25ab0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
25ac0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
25ad0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
25ae0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
25af0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
25b00 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
25b10 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
25b20 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
25b30 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
25b40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
25b50 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
25b60 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
25b70 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
25b80 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
25b90 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
25ba0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
25bb0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
25bc0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
25bd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
25be0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
25bf0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
25c00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
25c10 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25c20 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
25c30 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
25c40 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
25c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
25c60 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
25c70 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
25c80 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
25c90 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
25ca0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
25cb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
25cc0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
25cd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
25ce0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
25cf0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
25d00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
25d10 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
25d20 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
25d30 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
25d40 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
25d50 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
25d60 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
25d70 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
25d80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
25d90 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
25da0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
25db0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
25dc0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
25dd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25de0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
25df0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
25e00 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
25e10 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
25e20 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
25e30 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
25e40 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
25e50 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
25e60 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
25e70 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
25e80 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
25e90 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
25ea0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
25eb0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25ec0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
25ed0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
25ee0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
25ef0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
25f00 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
25f10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25f20 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
25f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25f40 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
25f50 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
25f60 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
25f70 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
25f80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
25f90 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
25fa0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
25fb0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
25fc0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
25fd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
25fe0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
25ff0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
26000 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
26010 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
26020 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
26030 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
26040 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
26050 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
26060 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26070 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
26080 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
26090 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
260a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
260b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
260c0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
260d0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
260e0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
260f0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
26100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26110 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
26120 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
26130 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
26140 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
26150 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
26160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26170 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
26180 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
26190 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
261a0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
261b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
261c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
261d0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
261e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
261f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
26200 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
26210 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
26220 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
26230 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
26240 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
26250 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
26260 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
26270 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
26280 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
26290 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
262a0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
262b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
262c0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
262d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
262e0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
262f0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
26300 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
26310 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
26320 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
26330 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
26340 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
26350 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
26360 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
26370 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
26380 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
26390 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
263a0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
263b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
263c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
263d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
263e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
263f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26400 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
26410 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26420 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
26430 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26440 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26450 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
26460 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
26470 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
26480 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
26490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
264a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
264b0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
264c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
264d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
264e0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
264f0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
26500 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26510 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
26520 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
26530 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
26540 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
26550 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
26560 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
26570 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
26580 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
26590 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
265a0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
265b0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
265c0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
265d0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
265e0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
265f0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
26600 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
26610 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
26620 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
26630 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
26640 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
26650 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
26660 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
26670 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
26680 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
26690 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
266a0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
266b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
266c0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
266d0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
266e0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
266f0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
26700 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
26710 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
26720 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
26730 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
26740 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26750 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
26760 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
26770 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
26780 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
26790 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
267a0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
267b0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
267c0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
267d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
267e0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
267f0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26800 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
26810 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
26820 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26830 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
26840 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
26850 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26860 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
26870 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26880 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26890 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
268a0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
268b0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
268c0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
268d0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
268e0 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
268f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
26900 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
26910 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
26920 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
26930 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
26940 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
26950 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
26960 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
26970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
26980 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
26990 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
269a0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
269b0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
269c0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
269d0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
269e0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
269f0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
26a00 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
26a10 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
26a20 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
26a30 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
26a40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
26a50 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
26a60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26a70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
26a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
26a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26aa0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
26ab0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
26ac0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26ad0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
26ae0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
26af0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26b00 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
26b10 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
26b20 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
26b30 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
26b40 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
26b50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26b60 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
26b70 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
26b80 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
26b90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
26ba0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
26bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
26bc0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
26bd0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
26be0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
26bf0 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
26c00 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
26c10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
26c20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
26c30 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
26c40 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
26c50 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
26c60 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
26c70 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
26c80 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
26c90 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
26ca0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26cb0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26cc0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
26cd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26ce0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
26cf0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
26d00 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
26d10 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
26d20 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
26d30 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
26d40 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
26d50 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
26d60 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
26d70 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
26d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
26d90 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
26da0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
26db0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26dc0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
26dd0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
26de0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
26df0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
26e00 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
26e10 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
26e20 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
26e30 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
26e40 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
26e50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
26e60 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
26e70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26e80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
26e90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26ea0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
26eb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
26ec0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
26ed0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
26ee0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
26ef0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
26f00 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
26f10 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
26f20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26f30 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
26f40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
26f50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
26f60 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
26f70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
26f80 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
26f90 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
26fa0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
26fb0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
26fc0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
26fd0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
26fe0 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
26ff0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27000 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
27010 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
27020 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
27030 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
27040 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
27050 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
27060 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
27070 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
27080 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
27090 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
270a0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
270b0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
270c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
270d0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
270e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
270f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
27100 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
27110 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
27120 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
27130 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
27140 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
27150 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
27160 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
27170 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
27180 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
27190 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
271a0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
271b0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
271c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
271d0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
271e0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
271f0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
27200 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
27210 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
27220 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
27230 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
27240 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
27250 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
27260 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
27270 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
27280 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
27290 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
272a0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
272b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
272c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
272d0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
272e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
272f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
27300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
27310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27320 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
27330 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
27340 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
27350 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
27360 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
27370 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
27380 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
27390 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
273a0 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
273b0 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
273c0 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
273d0 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
273e0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
273f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
27400 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
27410 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
27420 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
27430 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
27440 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
27450 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
27460 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
27470 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
27480 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
27490 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
274a0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
274b0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
274c0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
274d0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
274e0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
274f0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
27500 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
27510 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27520 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
27530 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
27540 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27550 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
27560 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
27570 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
27580 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
27590 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
275a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
275b0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
275c0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
275d0 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
275e0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
275f0 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
27600 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
27610 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
27620 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
27630 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
27640 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
27650 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
27660 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
27670 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
27680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27690 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
276a0 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
276b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
276c0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
276d0 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
276e0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
276f0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
27700 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
27710 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
27720 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
27730 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
27740 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
27750 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
27760 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
27770 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
27780 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
27790 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
277a0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
277b0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
277c0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
277d0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
277e0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
277f0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
27800 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
27810 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
27820 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
27830 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
27840 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
27850 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
27860 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
27870 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
27880 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
27890 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
278a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
278b0 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
278c0 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
278d0 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
278e0 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
278f0 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
27900 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
27910 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
27920 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
27930 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
27940 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
27950 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
27960 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
27970 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
27980 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
27990 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
279a0 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
279b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
279c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
279d0 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
279e0 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
279f0 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
27a00 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
27a10 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
27a20 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
27a30 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
27a40 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
27a50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27a60 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
27a70 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
27a80 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
27a90 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
27aa0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
27ab0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
27ac0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
27ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
27ae0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
27af0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
27b00 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
27b10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
27b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27b30 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
27b40 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
27b50 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
27b60 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27b70 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
27b80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27b90 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
27ba0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27bb0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
27bc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
27bd0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
27be0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
27bf0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
27c00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
27c10 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
27c20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27c30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27c40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27c50 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
27c60 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
27c70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27c80 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
27c90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27ca0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
27cb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
27cc0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
27cd0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27ce0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27cf0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
27d00 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
27d10 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
27d20 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
27d30 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
27d40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27d50 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
27d60 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
27d70 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
27d80 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
27d90 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
27da0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
27db0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
27dc0 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
27dd0 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
27de0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
27df0 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
27e00 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
27e10 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
27e20 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
27e30 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
27e40 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
27e50 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
27e60 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
27e70 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
27e80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
27e90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
27ea0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
27eb0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
27ec0 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
27ed0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
27ee0 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
27ef0 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
27f00 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
27f10 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
27f20 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
27f30 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
27f40 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
27f50 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
27f60 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
27f70 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
27f80 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
27f90 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
27fa0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
27fb0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
27fc0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
27fd0 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
27fe0 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
27ff0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
28000 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
28010 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
28020 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
28030 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
28040 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
28050 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
28060 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
28070 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
28080 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
28090 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
280a0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
280b0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
280c0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
280d0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
280e0 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
280f0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
28100 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
28110 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
28120 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
28130 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
28140 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
28150 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
28160 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
28170 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
28180 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28190 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
281a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
281b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
281c0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
281d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
281e0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
281f0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
28200 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
28210 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
28220 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28230 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
28240 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
28250 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
28260 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
28270 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28280 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
28290 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
282a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
282b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
282c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
282d0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
282e0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
282f0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
28300 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
28310 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
28320 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
28330 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
28340 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
28350 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
28360 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
28370 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
28380 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
28390 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
283a0 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
283b0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
283c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
283d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
283e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
283f0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
28400 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
28410 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
28420 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
28430 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
28440 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
28450 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
28460 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
28470 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
28480 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
28490 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
284a0 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
284b0 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
284c0 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
284d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
284e0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
284f0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
28500 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
28510 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
28520 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
28530 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
28540 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
28550 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
28560 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
28570 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
28580 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
28590 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
285a0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
285b0 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
285c0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
285d0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
285e0 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
285f0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
28600 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
28610 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
28620 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
28630 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
28640 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
28650 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
28660 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
28670 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
28680 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
28690 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
286a0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
286b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
286c0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
286d0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
286e0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
286f0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
28700 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
28710 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
28720 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
28730 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
28740 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
28750 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
28760 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
28770 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
28780 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
28790 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
287a0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
287b0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
287c0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
287d0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
287e0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
287f0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
28800 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28810 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
28820 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
28830 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
28840 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
28850 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
28860 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
28870 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
28880 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
28890 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
288a0 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
288b0 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
288c0 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
288d0 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
288e0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
288f0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
28900 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
28910 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
28920 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
28930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
28940 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
28950 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
28960 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
28970 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
28980 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
28990 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
289a0 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
289b0 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
289c0 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
289d0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
289e0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
289f0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
28a00 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
28a10 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
28a20 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
28a30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
28a40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
28a50 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
28a60 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
28a70 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
28a80 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
28a90 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
28aa0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
28ab0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
28ac0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
28ad0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
28ae0 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
28af0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
28b00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28b10 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
28b20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
28b30 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
28b40 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
28b50 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
28b60 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
28b70 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
28b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
28b90 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
28ba0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
28bb0 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
28bc0 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
28bd0 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
28be0 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
28bf0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
28c00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28c10 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
28c20 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
28c30 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
28c40 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
28c50 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
28c60 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
28c70 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
28c80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
28c90 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
28ca0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
28cb0 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
28cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28cd0 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
28ce0 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
28cf0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
28d00 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
28d10 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
28d20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
28d30 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
28d40 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
28d50 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
28d60 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
28d70 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
28d80 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
28d90 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
28da0 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
28db0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
28dc0 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
28dd0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
28de0 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
28df0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
28e00 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
28e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28e20 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
28e30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
28e40 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
28e50 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
28e60 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
28e70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
28e80 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
28e90 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
28ea0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
28eb0 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
28ec0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28ed0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
28ee0 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
28ef0 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
28f00 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
28f10 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
28f20 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
28f30 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
28f40 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
28f50 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
28f60 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
28f70 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
28f80 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
28f90 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
28fa0 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
28fb0 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
28fc0 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
28fd0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
28fe0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
28ff0 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
29000 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
29010 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
29020 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
29030 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
29040 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
29050 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
29060 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
29070 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
29080 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
29090 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
290a0 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
290b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
290c0 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
290d0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
290e0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
290f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
29110 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
29120 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
29130 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
29140 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
29150 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
29160 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
29170 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
29180 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
29190 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
291a0 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
291b0 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
291c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
291d0 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
291e0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
291f0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
29200 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
29210 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29220 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
29230 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
29240 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
29250 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
29260 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
29270 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29280 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
29290 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
292a0 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
292b0 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
292c0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
292d0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
292e0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
292f0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
29300 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
29310 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
29320 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
29330 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
29340 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29350 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
29360 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
29370 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
29380 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
29390 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
293a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
293b0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
293c0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
293d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
293e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
293f0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
29400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29410 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
29420 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
29430 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
29440 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
29450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
29460 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
29470 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
29480 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
29490 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
294a0 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
294b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
294c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
294d0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
294e0 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
294f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
29500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29510 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29520 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
29530 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
29540 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
29550 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
29560 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
29570 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
29580 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
29590 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
295a0 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
295b0 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
295c0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
295d0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
295e0 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
295f0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
29600 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
29610 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
29620 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
29630 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
29640 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
29650 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
29660 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
29670 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
29680 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
29690 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
296a0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
296b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
296c0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
296d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
296e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
296f0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
29700 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
29710 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
29720 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
29730 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
29740 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
29750 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
29760 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
29770 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
29780 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
29790 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
297a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
297b0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
297c0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
297d0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
297e0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
297f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
29800 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
29810 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
29820 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
29830 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
29840 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
29850 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
29860 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
29870 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
29880 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
29890 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
298a0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
298b0 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
298c0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
298d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
298e0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
298f0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
29900 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
29910 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
29920 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
29930 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
29940 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
29950 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
29960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
29970 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
29980 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
29990 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
299a0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
299b0 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
299c0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
299d0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
299e0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
299f0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
29a00 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
29a10 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
29a20 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
29a30 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
29a40 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
29a50 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
29a60 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
29a70 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
29a80 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
29a90 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
29aa0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
29ab0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
29ac0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
29ad0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
29ae0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
29af0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
29b00 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
29b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b20 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
29b30 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
29b40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
29b50 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
29b60 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
29b70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
29b80 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
29b90 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
29ba0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
29bb0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
29bc0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
29bd0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
29be0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
29bf0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
29c00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
29c10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29c20 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
29c30 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
29c40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29c50 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
29c60 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
29c70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
29c80 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
29c90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
29ca0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
29cb0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
29cc0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
29cd0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
29ce0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
29cf0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
29d00 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
29d10 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
29d20 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
29d30 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
29d40 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
29d50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
29d60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
29d70 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
29d80 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
29d90 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
29da0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
29db0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
29dc0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
29dd0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
29de0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
29df0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
29e00 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
29e10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29e20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
29e30 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
29e40 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
29e50 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
29e60 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
29e70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
29e80 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
29e90 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
29ea0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
29eb0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
29ec0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29ed0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
29ee0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
29ef0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
29f00 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
29f10 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
29f20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
29f30 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
29f40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
29f50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
29f60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
29f70 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
29f80 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
29f90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29fa0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
29fb0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
29fc0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
29fd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
29fe0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
29ff0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2a000 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2a010 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2a020 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2a030 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2a040 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2a050 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2a060 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2a070 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2a080 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2a090 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2a0a0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2a0b0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2a0c0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2a0d0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2a0e0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2a0f0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2a100 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a110 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2a120 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2a130 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2a140 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2a150 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2a160 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2a170 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2a180 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2a190 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2a1a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2a1b0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2a1c0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2a1d0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2a1e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2a1f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a200 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a210 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2a220 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2a230 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2a240 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2a250 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2a260 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2a270 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2a280 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2a290 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2a2a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2a2b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2a2c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2a2d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2a2e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2a2f0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2a300 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2a310 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2a320 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2a330 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2a340 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2a350 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2a360 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2a370 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a380 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2a390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a3a0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2a3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a3c0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2a3d0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2a3e0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2a3f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a400 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2a410 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2a420 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a430 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2a440 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2a450 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2a460 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2a470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a480 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2a490 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2a4a0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2a4b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2a4c0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2a4d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a4e0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2a4f0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2a500 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2a510 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2a520 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2a530 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2a540 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2a550 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2a560 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2a570 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2a580 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2a590 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2a5a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2a5b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a5c0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2a5d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2a5e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2a5f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a600 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2a610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a620 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2a630 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2a640 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2a650 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2a660 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2a670 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2a680 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2a690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2a6a0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2a6b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a6c0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2a6d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2a6e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2a6f0 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2a700 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2a710 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2a720 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2a730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2a740 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2a750 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a760 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2a770 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2a780 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2a790 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2a7a0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2a7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a7c0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2a7d0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2a7e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2a7f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2a800 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2a810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2a820 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2a830 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a840 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a850 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2a860 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a870 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2a880 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2a890 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2a8a0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2a8b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a8c0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2a8d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a8e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a8f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2a900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a910 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2a920 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2a930 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2a940 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2a950 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2a960 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2a970 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2a980 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2a990 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2a9a0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2a9b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2a9c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2a9d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2a9e0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2a9f0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2aa00 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2aa10 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2aa20 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2aa30 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2aa40 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2aa50 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2aa60 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2aa70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2aa80 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2aa90 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2aaa0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2aab0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2aac0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2aad0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2aae0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2aaf0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2ab00 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2ab10 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2ab20 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2ab30 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2ab40 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2ab50 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2ab60 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2ab70 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2ab80 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2ab90 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2aba0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2abb0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2abc0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2abd0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2abe0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2abf0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2ac00 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ac10 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2ac20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2ac30 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2ac40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ac50 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2ac60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2ac70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2ac80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2ac90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2aca0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2acb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2acc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2acd0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2ace0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2acf0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2ad00 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2ad10 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2ad20 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2ad30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2ad40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2ad50 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2ad60 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2ad70 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2ad80 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2ad90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2ada0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2adb0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2adc0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2add0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2ade0 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2adf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2ae00 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ae10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2ae20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2ae30 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2ae40 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2ae50 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2ae60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ae70 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2ae80 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2ae90 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2aea0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2aeb0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2aec0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2aed0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2aee0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2aef0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2af00 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2af10 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2af20 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2af30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2af40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2af50 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2af60 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2af70 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2af80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2af90 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2afa0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2afb0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2afc0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2afd0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2afe0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2aff0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2b000 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2b010 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2b020 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2b030 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2b040 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2b050 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2b060 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2b070 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2b080 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2b090 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2b0a0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2b0b0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2b0c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2b0d0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2b0e0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2b0f0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2b100 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2b110 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2b120 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2b130 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b140 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2b150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b160 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2b170 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2b180 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2b190 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2b1a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2b1b0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2b1c0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2b1d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2b1e0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2b1f0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2b200 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b210 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2b220 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2b230 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2b240 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2b250 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2b260 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2b270 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2b280 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2b290 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2b2a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2b2b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2b2c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b2d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2b2e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b2f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2b300 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2b310 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2b320 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2b330 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2b340 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2b350 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2b360 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2b370 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2b380 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2b390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2b3a0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2b3b0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2b3c0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2b3d0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2b3e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2b3f0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2b400 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2b410 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2b420 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2b430 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2b440 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2b450 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2b460 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2b470 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2b480 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2b490 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2b4a0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2b4b0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2b4c0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2b4d0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2b4e0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2b4f0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2b500 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2b510 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2b520 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2b530 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2b540 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2b550 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2b560 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2b570 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2b580 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2b590 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2b5a0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2b5b0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2b5c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2b5d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2b5e0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2b5f0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2b600 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2b610 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2b620 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2b630 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b640 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2b650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b660 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2b670 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2b680 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2b690 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2b6a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2b6b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2b6c0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2b6d0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2b6e0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2b6f0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2b700 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2b710 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2b720 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2b730 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2b740 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2b750 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2b760 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2b770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b780 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2b790 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b7a0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2b7b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2b7c0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2b7d0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2b7e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b7f0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2b800 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2b810 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2b820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b830 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2b840 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2b850 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b860 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2b870 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2b880 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2b890 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2b8a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2b8b0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2b8c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2b8d0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2b8e0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2b8f0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2b900 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2b910 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2b920 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2b930 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2b940 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2b950 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2b960 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2b970 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2b980 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2b990 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2b9a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2b9b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2b9c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2b9d0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2b9e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2b9f0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2ba00 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2ba10 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2ba20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2ba30 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2ba40 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2ba50 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2ba60 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2ba70 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2ba80 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2ba90 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2baa0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2bab0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2bac0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2bad0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2bae0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2baf0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2bb00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2bb10 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2bb20 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2bb30 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2bb40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2bb50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2bb60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2bb70 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2bb80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2bb90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2bba0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2bbb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2bbc0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2bbd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2bbe0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2bbf0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2bc00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2bc10 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2bc20 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2bc30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2bc40 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2bc50 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2bc60 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2bc70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2bc80 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2bc90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2bca0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2bcb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2bcc0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2bcd0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2bce0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2bcf0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2bd00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2bd10 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2bd20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2bd30 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2bd40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2bd50 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2bd60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2bd70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bd80 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2bd90 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2bda0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2bdb0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2bdc0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2bdd0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2bde0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2bdf0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2be00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2be10 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2be20 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2be30 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2be40 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2be50 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2be60 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2be70 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2be80 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2be90 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2bea0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2beb0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2bec0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2bed0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2bee0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2bef0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2bf00 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2bf10 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2bf20 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2bf30 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2bf40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bf50 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2bf60 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2bf70 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2bf80 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2bf90 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2bfa0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2bfb0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2bfc0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2bfd0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2bfe0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2bff0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2c000 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2c010 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2c020 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2c030 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2c040 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2c050 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2c060 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2c070 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2c080 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2c090 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2c0a0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2c0b0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2c0c0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2c0d0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2c0e0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2c0f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2c100 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2c110 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2c120 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2c130 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2c140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2c150 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2c160 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2c170 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2c180 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2c190 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2c1a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2c1b0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2c1c0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2c1d0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2c1e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2c1f0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2c200 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2c210 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2c220 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2c230 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2c240 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2c250 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2c260 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2c270 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2c280 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2c290 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2c2a0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2c2b0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2c2c0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2c2d0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2c2e0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2c2f0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2c300 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2c310 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2c320 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2c330 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2c340 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2c350 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2c360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2c370 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2c380 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2c390 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2c3a0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2c3b0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2c3c0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2c3d0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2c3e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2c3f0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2c400 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2c410 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c420 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2c430 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2c440 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2c450 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2c460 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2c470 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2c480 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2c490 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c4a0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2c4b0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2c4c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2c4d0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2c4e0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2c4f0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2c500 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2c510 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2c520 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2c530 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2c540 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2c550 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2c560 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2c570 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2c580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c590 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2c5a0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2c5b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2c5c0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2c5d0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c5e0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2c5f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c600 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2c610 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2c620 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2c630 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2c640 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2c650 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2c660 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2c670 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2c680 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2c690 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c6a0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2c6b0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2c6c0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2c6d0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2c6e0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2c6f0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2c700 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2c710 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c720 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2c730 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2c740 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c750 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2c760 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2c770 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2c780 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2c790 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2c7a0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2c7b0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2c7c0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2c7d0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2c7e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2c7f0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2c800 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2c810 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2c820 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2c830 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2c840 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2c850 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2c860 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2c870 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2c880 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2c890 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2c8a0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2c8b0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2c8c0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2c8d0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2c8e0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2c8f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2c900 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2c910 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2c920 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2c930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c940 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2c950 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2c960 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2c970 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2c980 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2c990 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2c9a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2c9b0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2c9c0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2c9d0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2c9e0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2c9f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ca00 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2ca10 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2ca20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ca30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2ca40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2ca50 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2ca60 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2ca70 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2ca80 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2ca90 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2caa0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2cab0 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2cac0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2cad0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2cae0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2caf0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2cb00 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2cb10 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2cb20 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2cb30 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2cb40 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2cb50 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2cb60 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2cb70 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2cb80 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2cb90 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2cba0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2cbb0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2cbc0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2cbd0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2cbe0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2cbf0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2cc00 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2cc10 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2cc20 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2cc30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2cc40 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2cc50 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2cc60 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2cc70 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2cc80 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2cc90 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2cca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2ccb0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2ccc0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2ccd0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2cce0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2ccf0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2cd00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2cd10 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2cd20 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2cd30 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2cd40 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2cd50 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2cd60 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2cd70 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2cd80 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2cd90 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2cda0 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2cdb0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2cdc0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2cdd0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2cde0 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2cdf0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2ce00 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2ce10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2ce20 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2ce30 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2ce40 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2ce50 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2ce60 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2ce70 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2ce80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ce90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2cea0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2ceb0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2cec0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2ced0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2cee0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2cef0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2cf00 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2cf10 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2cf20 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2cf30 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2cf40 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2cf50 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2cf60 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2cf70 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2cf80 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2cf90 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2cfa0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2cfb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2cfc0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2cfd0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2cfe0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2cff0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2d000 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2d010 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2d020 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2d030 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2d040 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2d050 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2d060 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d070 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2d080 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2d090 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2d0a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d0b0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2d0c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2d0d0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2d0e0 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2d0f0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2d100 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2d110 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2d120 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2d130 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2d140 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d150 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2d160 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2d170 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2d180 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2d190 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2d1a0 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2d1b0 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2d1c0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2d1d0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2d1e0 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2d1f0 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2d200 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2d210 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2d220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2d230 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2d240 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2d250 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2d260 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2d270 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2d280 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2d290 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2d2a0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2d2b0 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2d2c0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2d2d0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2d2e0 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2d2f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2d300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d310 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2d320 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2d330 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2d340 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2d350 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2d360 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2d370 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2d380 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2d390 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2d3a0 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2d3b0 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2d3c0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2d3d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2d3e0 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2d3f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2d400 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2d410 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2d420 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d430 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2d440 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2d450 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2d460 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2d470 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2d480 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2d490 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2d4a0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2d4b0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2d4c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2d4d0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2d4e0 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2d4f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d500 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d510 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2d520 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2d530 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2d540 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2d550 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2d560 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2d570 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2d580 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2d590 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2d5a0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2d5b0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2d5c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2d5d0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2d5e0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2d5f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2d600 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2d610 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2d620 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2d630 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2d640 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2d650 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2d660 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2d670 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2d680 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2d690 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2d6a0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2d6b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2d6c0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2d6d0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2d6e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2d6f0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2d700 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2d710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2d720 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2d730 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2d740 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2d750 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2d760 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2d770 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
2d780 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2d790 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2d7a0 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2d7b0 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2d7c0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2d7d0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2d7e0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2d7f0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2d800 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2d810 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2d820 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
2d830 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
2d840 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
2d850 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d860 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
2d870 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
2d880 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2d890 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
2d8a0 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
2d8b0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
2d8c0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
2d8d0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
2d8e0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
2d8f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d900 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
2d910 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
2d920 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d930 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
2d940 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
2d950 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
2d960 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d970 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2d980 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2d990 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2d9a0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2d9b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2d9c0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2d9d0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2d9e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2d9f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2da00 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2da10 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2da20 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2da30 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2da40 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2da50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2da60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2da70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2da80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2da90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2daa0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2dab0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2dac0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2dad0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2dae0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2daf0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2db00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2db10 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2db20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2db30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2db40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2db50 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2db60 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2db70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2db80 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
2db90 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2dba0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2dbb0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2dbc0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2dbd0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2dbe0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2dbf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2dc00 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2dc10 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2dc20 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2dc30 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2dc40 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2dc50 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2dc60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2dc70 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2dc80 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
2dc90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2dca0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
2dcb0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2dcc0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
2dcd0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
2dce0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
2dcf0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
2dd00 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
2dd10 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
2dd20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
2dd30 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
2dd40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2dd50 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
2dd60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2dd70 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
2dd80 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2dd90 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
2dda0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
2ddb0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
2ddc0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
2ddd0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
2dde0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2ddf0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
2de00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2de10 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
2de20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
2de30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2de40 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
2de50 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
2de60 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
2de70 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
2de80 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2de90 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
2dea0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
2deb0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
2dec0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2ded0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
2dee0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
2def0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2df00 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
2df10 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
2df20 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2df30 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
2df40 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
2df50 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
2df60 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
2df70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
2df80 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
2df90 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
2dfa0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
2dfb0 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
2dfc0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
2dfd0 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
2dfe0 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
2dff0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2e000 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e010 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2e020 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
2e030 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2e040 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2e050 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2e060 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2e070 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
2e080 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
2e090 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
2e0a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2e0b0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2e0c0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2e0d0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2e0e0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2e0f0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
2e100 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
2e110 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2e120 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2e130 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
2e140 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
2e150 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
2e160 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
2e170 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
2e180 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2e190 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2e1a0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2e1b0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
2e1c0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
2e1d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
2e1e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2e1f0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
2e200 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
2e210 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2e220 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
2e230 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
2e240 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
2e250 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2e260 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
2e270 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
2e280 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
2e290 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
2e2a0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
2e2b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2e2c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2e2d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2e2e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2e2f0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
2e300 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
2e310 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2e320 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2e330 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
2e340 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2e350 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
2e360 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
2e370 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
2e380 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e390 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
2e3a0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
2e3b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e3c0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
2e3d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2e3e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
2e3f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2e400 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
2e410 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
2e420 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2e430 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2e440 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2e450 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
2e460 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
2e470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e480 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
2e490 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
2e4a0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
2e4b0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2e4c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2e4d0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
2e4e0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
2e4f0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
2e500 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2e510 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2e520 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2e530 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2e540 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2e550 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2e560 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2e570 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2e580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2e590 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2e5a0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2e5b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2e5c0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2e5d0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2e5e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2e5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e600 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
2e610 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
2e620 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
2e630 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
2e640 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
2e650 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
2e660 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e670 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
2e680 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e690 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
2e6a0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
2e6b0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
2e6c0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2e6d0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2e6e0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2e6f0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
2e700 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2e710 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2e720 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2e730 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2e740 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2e750 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2e760 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2e770 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2e780 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2e790 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2e7a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2e7b0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2e7c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2e7d0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2e7e0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2e7f0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2e800 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2e810 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2e820 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2e830 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2e840 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2e850 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2e860 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2e870 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2e880 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2e890 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2e8a0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2e8b0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2e8c0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
2e8d0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
2e8e0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
2e8f0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
2e900 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
2e910 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2e920 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2e930 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e940 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2e950 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e960 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2e970 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2e980 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2e990 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2e9a0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2e9b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2e9c0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2e9d0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2e9e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2e9f0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
2ea00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ea10 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2ea20 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2ea30 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
2ea40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
2ea50 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
2ea60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
2ea70 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
2ea80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ea90 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2eaa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2eab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2eac0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2ead0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2eae0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2eaf0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2eb00 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2eb10 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2eb20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2eb30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2eb40 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2eb50 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2eb60 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2eb70 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2eb80 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2eb90 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2eba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ebb0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2ebc0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2ebd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ebe0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2ebf0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2ec00 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2ec10 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2ec20 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ec30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2ec40 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2ec50 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ec60 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2ec70 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2ec80 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2ec90 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2eca0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2ecb0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2ecc0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2ecd0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2ece0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2ecf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2ed00 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2ed10 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2ed20 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2ed30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2ed40 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2ed50 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2ed60 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2ed70 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2ed80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2ed90 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2eda0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2edb0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2edc0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2edd0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2ede0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2edf0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2ee00 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2ee10 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2ee20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2ee30 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2ee40 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2ee50 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2ee60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2ee70 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2ee80 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2ee90 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2eea0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2eeb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2eec0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2eed0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2eee0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2eef0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2ef00 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2ef10 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2ef20 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2ef30 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2ef40 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2ef50 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2ef60 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2ef70 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2ef80 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2ef90 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2efa0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2efb0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2efc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2efd0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2efe0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2eff0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2f000 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2f010 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2f020 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f030 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2f040 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2f050 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2f060 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2f070 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f080 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f090 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2f0a0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2f0b0 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2f0c0 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2f0d0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2f0e0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2f0f0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2f100 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2f110 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2f120 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2f130 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f140 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2f150 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2f160 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2f170 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2f180 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2f190 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2f1a0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2f1b0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2f1c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f1d0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2f1e0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2f1f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2f200 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2f210 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2f220 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2f230 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2f240 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2f250 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2f260 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2f270 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2f280 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2f290 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2f2a0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2f2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2f2c0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2f2d0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2f2e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2f2f0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2f300 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2f310 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2f320 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2f330 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2f340 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2f350 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2f360 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2f370 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2f380 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2f390 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2f3a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f3b0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f3c0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2f3d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2f3e0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
2f3f0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2f400 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2f410 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2f420 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2f430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2f440 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2f450 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2f460 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f470 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2f480 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2f490 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2f4a0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2f4b0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2f4c0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2f4d0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2f4e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f4f0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2f500 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f510 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2f520 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2f530 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2f540 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2f550 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2f560 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2f570 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2f580 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2f590 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2f5a0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2f5b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f5c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
2f5d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2f5e0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2f5f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2f600 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2f610 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2f620 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2f630 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
2f640 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2f650 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2f660 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f670 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2f680 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2f690 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f6a0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2f6b0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2f6c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2f6d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2f6e0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2f6f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f700 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2f710 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2f720 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2f730 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2f740 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2f750 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2f760 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f770 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2f780 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2f790 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2f7a0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2f7b0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
2f7c0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
2f7d0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
2f7e0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
2f7f0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
2f800 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
2f810 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
2f820 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
2f830 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
2f840 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
2f850 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
2f860 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
2f870 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
2f880 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
2f890 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
2f8a0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
2f8b0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
2f8c0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2f8d0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2f8e0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2f8f0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2f900 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2f910 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2f920 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2f930 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2f940 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2f950 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2f960 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2f970 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2f980 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2f990 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2f9a0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2f9b0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2f9c0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2f9d0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f9e0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2f9f0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2fa00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2fa10 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2fa20 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2fa30 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2fa40 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2fa50 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2fa60 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2fa70 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2fa80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
2fa90 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
2faa0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2fab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2fac0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
2fad0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
2fae0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2faf0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
2fb00 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
2fb10 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
2fb20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fb30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2fb40 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
2fb50 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
2fb60 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
2fb70 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
2fb80 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
2fb90 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
2fba0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
2fbb0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
2fbc0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
2fbd0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2fbe0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
2fbf0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2fc00 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
2fc10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2fc20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fc30 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2fc40 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2fc50 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
2fc60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
2fc70 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
2fc80 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
2fc90 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2fca0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2fcb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fcc0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2fcd0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2fce0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2fcf0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2fd00 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2fd10 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2fd20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2fd30 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
2fd40 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2fd50 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2fd60 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2fd70 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
2fd80 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
2fd90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
2fda0 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
2fdb0 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
2fdc0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
2fdd0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
2fde0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2fdf0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2fe00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
2fe10 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
2fe20 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
2fe30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
2fe40 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
2fe50 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
2fe60 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
2fe70 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
2fe80 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2fe90 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2fea0 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
2feb0 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
2fec0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
2fed0 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
2fee0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
2fef0 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
2ff00 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
2ff10 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
2ff20 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
2ff30 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
2ff40 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
2ff50 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
2ff60 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
2ff70 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
2ff80 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
2ff90 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
2ffa0 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
2ffb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2ffc0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2ffd0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2ffe0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2fff0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30000 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
30010 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
30020 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
30030 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
30040 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30050 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
30060 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30070 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
30080 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
30090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
300a0 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
300b0 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
300c0 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
300d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
300e0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
300f0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
30100 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
30110 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
30120 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
30130 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
30140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
30150 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
30160 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
30170 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
30180 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
30190 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
301a0 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
301b0 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
301c0 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
301d0 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
301e0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
301f0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
30200 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
30210 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
30220 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
30230 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
30240 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
30250 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
30260 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
30270 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
30280 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
30290 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
302a0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
302b0 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
302c0 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
302d0 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
302e0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
302f0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
30300 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
30310 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
30320 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
30330 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
30340 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
30350 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
30360 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
30370 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
30380 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
30390 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
303a0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
303b0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
303c0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
303d0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
303e0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
303f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
30400 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
30410 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
30420 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
30430 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
30440 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
30450 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
30460 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30470 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
30480 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30490 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
304a0 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
304b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
304c0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
304d0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
304e0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
304f0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
30500 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
30510 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
30520 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
30530 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
30540 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30550 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
30560 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
30570 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
30580 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
30590 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
305a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
305b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
305c0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
305d0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
305e0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
305f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30600 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
30610 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
30620 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
30630 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
30640 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
30650 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
30660 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
30670 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
30680 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
30690 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
306a0 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
306b0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
306c0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
306d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
306e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
306f0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
30700 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
30710 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
30720 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
30730 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
30740 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
30750 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
30760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30770 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
30780 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
30790 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
307a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
307b0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
307c0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
307d0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
307e0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
307f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
30800 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30810 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
30820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30830 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
30840 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
30850 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
30860 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
30870 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
30880 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
30890 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
308a0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
308b0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
308c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
308d0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
308e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
308f0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
30900 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
30910 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
30920 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
30930 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
30940 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
30950 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30960 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
30970 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
30980 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
30990 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
309a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
309b0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
309c0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
309d0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
309e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
309f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30a00 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30a10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30a20 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
30a30 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
30a40 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
30a50 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
30a60 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
30a70 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
30a80 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
30a90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
30aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
30ab0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
30ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ad0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
30ae0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
30af0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
30b00 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
30b10 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
30b20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
30b30 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
30b40 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
30b50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30b60 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
30b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30b80 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
30b90 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
30ba0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
30bb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30bc0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
30bd0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
30be0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
30bf0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
30c00 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
30c10 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
30c20 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
30c30 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
30c40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30c50 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
30c60 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
30c70 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
30c80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
30c90 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
30ca0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
30cb0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
30cc0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
30cd0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
30ce0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
30cf0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
30d00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
30d10 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
30d20 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30d30 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
30d40 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
30d50 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
30d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
30d80 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
30d90 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
30da0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
30db0 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
30dc0 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
30dd0 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
30de0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
30df0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30e00 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
30e10 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
30e20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
30e30 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
30e40 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
30e50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
30e60 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
30e70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30e80 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
30e90 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
30ea0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
30eb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30ec0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30ed0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
30ee0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
30ef0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
30f00 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
30f10 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
30f20 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
30f30 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30f40 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
30f50 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
30f60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30f70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
30f80 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
30f90 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
30fa0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
30fb0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
30fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30fd0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
30fe0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30ff0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
31000 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31010 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31020 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
31030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31040 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
31050 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
31060 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
31070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31080 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
31090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
310a0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
310b0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
310c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
310d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
310e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
310f0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
31100 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
31110 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
31120 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
31130 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
31140 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
31150 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
31160 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
31170 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
31180 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
31190 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
311a0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
311b0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
311c0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
311d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
311e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
311f0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
31200 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
31210 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31220 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31230 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
31240 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
31250 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
31260 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
31270 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
31280 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
31290 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
312a0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
312b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
312c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
312d0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
312e0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
312f0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
31300 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
31310 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
31320 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
31330 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
31340 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
31350 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
31360 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
31370 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
31380 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31390 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
313a0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
313b0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
313c0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
313d0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
313e0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
313f0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
31400 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
31410 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
31420 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
31430 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
31440 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
31450 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
31460 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
31470 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
31480 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
31490 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
314a0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
314b0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
314c0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
314d0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
314e0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
314f0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
31500 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
31510 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
31520 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
31530 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
31540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31550 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
31560 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
31570 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
31580 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
31590 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
315a0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
315b0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
315c0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
315d0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
315e0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
315f0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
31600 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
31610 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
31620 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31640 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31650 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
31660 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
31670 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
31680 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
31690 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
316a0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
316b0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
316c0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
316d0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
316e0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
316f0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
31700 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
31710 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
31720 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
31730 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
31740 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
31750 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
31760 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
31770 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
31780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31790 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
317a0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
317b0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
317c0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
317d0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
317e0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
317f0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
31800 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
31810 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
31820 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
31830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
31840 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
31850 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
31860 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31870 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
31880 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31890 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
318a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
318b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
318c0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
318d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
318e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
318f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
31900 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
31910 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
31920 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
31930 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
31940 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
31950 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
31960 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
31970 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
31980 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
31990 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
319a0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
319b0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
319c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
319d0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
319e0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
319f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31a00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31a10 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
31a20 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
31a30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
31a40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31a50 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
31a60 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
31a70 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
31a80 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
31a90 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
31aa0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
31ab0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
31ac0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
31ad0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
31ae0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
31af0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
31b00 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
31b10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31b20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
31b30 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
31b40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
31b50 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
31b60 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
31b70 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
31b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31b90 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
31ba0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31bb0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
31bc0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
31bd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
31be0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
31bf0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
31c00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31c10 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
31c20 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
31c30 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
31c40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31c50 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
31c60 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
31c70 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
31c80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31c90 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
31ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31cb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31cc0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
31cd0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
31ce0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
31cf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
31d00 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
31d10 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
31d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31d30 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
31d40 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
31d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31d60 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
31d70 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
31d80 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
31d90 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
31da0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31db0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
31dc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
31dd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31de0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
31df0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
31e00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31e10 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
31e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31e30 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31e40 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
31e50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31e60 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
31e70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31e80 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
31e90 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
31ea0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31eb0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
31ec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31ed0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31ee0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
31ef0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
31f00 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
31f10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31f20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31f30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31f40 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
31f50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31f60 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
31f70 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
31f80 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
31f90 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
31fa0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
31fb0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
31fc0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
31fd0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
31fe0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
31ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32000 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
32010 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
32020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
32030 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
32040 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
32050 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
32060 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32070 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
32080 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32090 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
320a0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
320b0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
320c0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
320d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
320e0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
320f0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
32100 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
32110 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
32120 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
32130 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
32140 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
32150 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
32160 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
32170 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
32180 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
32190 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
321a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
321b0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
321c0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
321d0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
321e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
321f0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32200 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
32210 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
32220 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
32230 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
32240 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
32250 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
32260 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
32270 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
32280 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
32290 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
322a0 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
322b0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
322c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
322d0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
322e0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
322f0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
32300 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
32310 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
32320 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
32330 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32340 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
32350 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
32360 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
32370 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
32380 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
32390 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
323a0 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
323b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
323c0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
323d0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
323e0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
323f0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
32400 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
32410 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
32420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
32430 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
32440 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
32450 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
32460 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
32470 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
32480 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
32490 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
324a0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
324b0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
324c0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
324d0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
324e0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
324f0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
32500 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
32510 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
32520 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
32530 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
32540 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
32550 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
32560 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
32570 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
32580 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
32590 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
325a0 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
325b0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
325c0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
325d0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
325e0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
325f0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
32600 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32610 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
32620 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
32630 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
32640 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
32650 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
32660 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
32670 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
32680 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
32690 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
326a0 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
326b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
326c0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
326d0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
326e0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
326f0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
32700 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
32710 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
32720 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
32730 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
32740 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
32750 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
32760 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
32770 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
32780 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
32790 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
327a0 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
327b0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
327c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
327d0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
327e0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
327f0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
32800 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
32810 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
32820 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
32830 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
32840 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
32850 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
32860 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
32870 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
32880 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
32890 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
328a0 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
328b0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
328c0 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
328d0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
328e0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
328f0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
32900 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
32910 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
32920 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
32930 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
32940 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
32950 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
32960 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
32970 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
32980 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
32990 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
329a0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
329b0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
329c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
329d0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
329e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
329f0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
32a00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
32a10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32a20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32a30 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
32a40 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
32a50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
32a60 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
32a70 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
32a80 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
32a90 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
32aa0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
32ab0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32ac0 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
32ad0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
32ae0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
32af0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
32b00 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
32b10 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
32b20 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
32b30 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
32b40 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
32b50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32b60 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
32b70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
32b80 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
32b90 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
32ba0 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
32bb0 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
32bc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
32bd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32be0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
32bf0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
32c00 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
32c10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32c20 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
32c30 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
32c40 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
32c50 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
32c60 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
32c70 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
32c80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
32c90 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
32ca0 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
32cb0 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
32cc0 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
32cd0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
32ce0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
32cf0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
32d00 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
32d10 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
32d20 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
32d30 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
32d40 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
32d50 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
32d60 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
32d70 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
32d80 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
32d90 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
32da0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
32db0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
32dc0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
32dd0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
32de0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32df0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
32e00 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
32e10 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
32e20 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
32e30 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
32e40 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
32e50 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
32e60 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
32e70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32e80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32e90 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
32ea0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32eb0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
32ec0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
32ed0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
32ee0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
32ef0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
32f00 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
32f10 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
32f20 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
32f30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32f40 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
32f50 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
32f60 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
32f70 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
32f80 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
32f90 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
32fa0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
32fb0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
32fc0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
32fd0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
32fe0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
32ff0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
33000 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
33010 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
33020 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
33030 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
33040 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
33050 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
33060 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
33070 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
33080 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
33090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
330a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
330b0 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
330c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
330d0 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
330e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
330f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
33100 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
33110 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
33120 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
33130 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
33140 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
33150 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
33160 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33170 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
33180 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
33190 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
331a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
331b0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
331c0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
331d0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
331e0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
331f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
33200 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
33210 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
33220 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
33230 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
33240 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
33250 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
33260 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33270 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
33280 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
33290 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
332a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
332b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
332c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
332d0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
332e0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
332f0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
33300 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
33310 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
33320 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
33330 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
33340 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
33350 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
33360 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
33370 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
33380 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
33390 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
333a0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
333b0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
333c0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
333d0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
333e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
333f0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
33400 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
33410 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
33420 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
33430 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
33440 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
33450 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
33460 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
33470 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33480 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
33490 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
334a0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
334b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
334c0 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
334d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
334e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
334f0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
33500 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
33510 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
33520 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
33530 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
33540 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33550 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
33560 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
33570 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
33580 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
33590 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
335a0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
335b0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
335c0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
335d0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
335e0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
335f0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
33600 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
33610 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
33620 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
33630 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
33640 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
33650 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
33660 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
33670 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
33680 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
33690 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
336a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
336b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
336c0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
336d0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
336e0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
336f0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
33700 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
33710 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
33720 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
33730 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
33740 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
33750 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
33760 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
33770 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
33780 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
33790 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
337a0 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
337b0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
337c0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
337d0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
337e0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
337f0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
33800 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
33810 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
33820 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
33830 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33840 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
33850 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
33860 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
33870 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
33880 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
33890 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
338a0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
338b0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
338c0 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
338d0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
338e0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
338f0 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
33900 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
33910 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
33920 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
33930 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
33940 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
33950 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
33960 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
33970 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
33980 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
33990 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
339a0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
339b0 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
339c0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
339d0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
339e0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
339f0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
33a00 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
33a10 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
33a20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
33a30 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
33a40 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
33a50 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
33a60 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
33a70 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
33a80 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
33a90 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65  t Time.**.** The
33aa0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
33ab0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
33ac0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
33ad0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
33ae0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
33af0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
33b00 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
33b10 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
33b20 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
33b30 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
33b40 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
33b50 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
33b60 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
33b70 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
33b80 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
33b90 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
33ba0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
33bb0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
33bc0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
33bd0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
33be0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
33bf0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
33c00 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
33c10 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
33c20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
33c30 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65  ** ^SQLite imple
33c40 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
33c50 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
33c60 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
33c70 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
33c80 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
33c90 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  fs] object.  If 
33ca0 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
33cb0 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65  hod.** of the de
33cc0 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74  fault VFS is not
33cd0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72   implemented cor
33ce0 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69  rectly, or not i
33cf0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a  mplemented at.**
33d00 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62   all, then the b
33d10 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
33d20 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64  e3_sleep() may d
33d30 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20  eviate from the 
33d40 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69  description.** i
33d50 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
33d60 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e  aragraphs..*/.in
33d70 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
33d80 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
33d90 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
33da0 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
33db0 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
33dc0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
33dd0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
33de0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
33df0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
33e00 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
33e10 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
33e20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
33e30 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
33e40 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
33e50 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
33e60 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
33e70 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
33e80 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
33e90 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
33ea0 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
33eb0 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
33ec0 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
33ed0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
33ee0 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
33ef0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
33f00 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
33f10 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
33f20 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
33f30 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
33f40 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
33f50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
33f60 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
33f70 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
33f80 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
33f90 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
33fa0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
33fb0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
33fc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33fd0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
33fe0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
33ff0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
34000 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
34010 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
34020 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
34030 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
34040 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
34050 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
34060 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
34070 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
34080 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
34090 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
340a0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
340b0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
340c0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
340d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
340e0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
340f0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
34100 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
34110 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
34120 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
34130 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
34140 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
34150 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
34160 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
34170 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
34180 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
34190 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
341a0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
341b0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
341c0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
341d0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
341e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
341f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
34200 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
34210 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
34220 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
34230 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
34240 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
34250 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
34260 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
34270 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
34280 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
34290 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
342a0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
342b0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
342c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
342d0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
342e0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
342f0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
34300 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
34310 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
34320 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
34330 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
34340 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
34350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34360 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
34370 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
34380 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
34390 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
343a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
343b0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
343c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
343d0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
343e0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
343f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34400 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
34410 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
34420 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
34430 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
34440 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
34450 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
34460 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
34470 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
34480 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
34490 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
344a0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
344b0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
344c0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
344d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
344e0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
344f0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
34500 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
34510 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
34520 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34530 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
34540 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
34550 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
34560 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
34570 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
34580 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
34590 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
345a0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
345b0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
345c0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
345d0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
345e0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
345f0 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
34600 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
34610 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
34620 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
34630 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
34640 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
34650 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
34660 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
34670 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
34680 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
34690 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
346a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
346b0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
346c0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
346d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
346e0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
346f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34700 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
34710 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
34720 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
34730 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
34740 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
34750 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
34760 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34770 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
34780 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
34790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
347a0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
347b0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
347c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
347d0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
347e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
347f0 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
34800 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
34810 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
34820 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34830 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
34840 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
34850 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
34860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
34870 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
34880 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
34890 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
348a0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
348b0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
348c0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
348d0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
348e0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
348f0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
34900 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
34910 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
34920 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
34930 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
34940 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
34950 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
34960 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34970 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
34980 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
34990 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
349a0 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
349b0 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
349c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
349d0 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
349e0 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
349f0 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
34a00 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on th
34a10 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34a20 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69  nnection D, or i
34a30 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20  f database N is 
34a40 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69  a temporary or i
34a50 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
34a60 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c  e, then.** a NUL
34a70 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
34a80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
34a90 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72  e filename retur
34aa0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
34ab0 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70  tion is the outp
34ac0 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75  ut of the.** xFu
34ad0 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f  llPathname metho
34ae0 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20  d of the [VFS]. 
34af0 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   ^In other words
34b00 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  , the filename.*
34b10 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73  * will be an abs
34b20 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20  olute pathname, 
34b30 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65  even if the file
34b40 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20  name used.** to 
34b50 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
34b60 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73  e originally was
34b70 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69   a URI or relati
34b80 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a  ve pathname..*/.
34b90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
34ba0 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
34bb0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
34bc0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
34bd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34be0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
34bf0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
34c00 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
34c10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34c20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
34c30 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
34c40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
34c50 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
34c60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
34c70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34c80 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
34c90 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
34ca0 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
34cb0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
34cc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
34cd0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
34ce0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
34cf0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
34d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34d10 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
34d20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34d30 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
34d40 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
34d50 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
34d60 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
34d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
34d80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34d90 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
34da0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
34db0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
34dc0 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
34dd0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
34de0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
34df0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
34e00 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
34e10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
34e20 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
34e30 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
34e40 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
34e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
34e60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
34e70 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
34e80 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
34e90 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
34ea0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
34eb0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
34ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
34ed0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
34ee0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
34ef0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
34f00 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
34f10 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
34f20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
34f30 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
34f40 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
34f50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
34f60 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
34f70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
34f80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34f90 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
34fa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34fb0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
34fc0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
34fd0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
34fe0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
34ff0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
35000 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
35010 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
35020 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
35030 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
35040 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
35050 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
35060 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
35070 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
35080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35090 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
350a0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
350b0 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
350c0 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
350d0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
350e0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
350f0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
35100 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
35110 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
35120 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
35130 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
35140 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
35150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35160 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
35170 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
35180 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
35190 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
351a0 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
351b0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
351c0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
351d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
351e0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
351f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35200 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
35210 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
35220 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
35230 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
35240 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69  .**.** The commi
35250 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68  t and rollback h
35260 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72  ook callbacks ar
35270 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  e not reentrant.
35280 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
35290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
352a0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
352b0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
352c0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
352d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
352e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
352f0 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
35300 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
35310 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
35320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
35330 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
35340 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
35350 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
35360 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
35370 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
35380 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
35390 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
353a0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
353b0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
353c0 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67  ote that running
353d0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73   any other SQL s
353e0 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75  tatements, inclu
353f0 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74  ding SELECT stat
35400 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65  ements,.** or me
35410 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  rely calling [sq
35420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
35430 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35440 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f  _step()] will mo
35450 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
35460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
35470 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
35480 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
35490 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
354a0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
354b0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
354c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
354d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
354e0 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
354f0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
35500 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
35510 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
35520 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
35530 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
35540 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
35550 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
35560 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
35570 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
35580 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
35590 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
355a0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
355b0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
355c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
355d0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
355e0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
355f0 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
35600 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
35610 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
35620 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
35630 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
35640 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
35650 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
35660 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
35670 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
35680 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
35690 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
356a0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
356b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
356c0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
356d0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
356e0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
356f0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
35700 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
35710 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
35720 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
35730 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
35740 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
35750 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
35760 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
35770 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35780 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
35790 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
357a0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
357b0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
357c0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
357d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
357e0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
357f0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
35800 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
35810 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
35820 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
35830 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
35840 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35850 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
35860 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
35870 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
35880 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
35890 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
358a0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
358b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
358c0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
358d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
358e0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
358f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35900 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
35910 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
35920 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
35930 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
35940 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
35950 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
35960 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
35970 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
35980 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
35990 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
359a0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
359b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
359c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
359d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
359e0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
359f0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
35a00 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
35a10 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
35a20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
35a30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
35a40 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
35a50 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
35a60 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
35a70 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35a80 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
35a90 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
35aa0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
35ab0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
35ac0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
35ad0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
35ae0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
35af0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
35b00 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
35b10 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
35b20 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
35b30 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
35b40 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
35b50 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
35b60 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
35b70 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
35b80 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
35b90 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
35ba0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
35bb0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
35bc0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
35bd0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
35be0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
35bf0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
35c00 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
35c10 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
35c20 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
35c30 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
35c40 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
35c50 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
35c60 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
35c70 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
35c80 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
35c90 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
35ca0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
35cb0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
35cc0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
35cd0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
35ce0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
35cf0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
35d00 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
35d10 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
35d20 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
35d30 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
35d40 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
35d50 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
35d60 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
35d70 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
35d80 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
35d90 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
35da0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
35db0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
35dc0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
35dd0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
35de0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
35df0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
35e00 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
35e10 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
35e20 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
35e30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35e40 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
35e50 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
35e60 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
35e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35e80 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
35e90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
35ea0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
35eb0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
35ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35ed0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
35ee0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
35ef0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
35f00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35f10 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
35f20 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
35f30 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
35f40 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
35f50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
35f60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
35f70 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
35f80 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
35f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
35fa0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
35fb0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
35fc0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
35fd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35fe0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
35ff0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
36000 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
36010 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
36020 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
36030 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
36040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36050 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
36060 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
36070 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
36080 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
36090 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
360a0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
360b0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
360c0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
360d0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
360e0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
360f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36100 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
36110 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
36120 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
36130 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
36140 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
36150 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
36160 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
36170 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
36180 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
36190 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
361a0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
361b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
361c0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
361d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
361e0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
361f0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
36200 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
36210 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36220 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
36230 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
36240 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
36250 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
36260 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
36270 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
36280 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
36290 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
362a0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
362b0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
362c0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
362d0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
362e0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
362f0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
36300 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
36310 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
36320 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
36330 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
36340 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
36350 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
36360 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
36370 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
36380 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
36390 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
363a0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
363b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
363c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
363d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
363e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
363f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
36400 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
36410 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
36420 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
36430 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
36440 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
36450 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
36460 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
36470 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
36480 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
36490 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
364a0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
364b0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
364c0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
364d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
364e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
364f0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
36500 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
36510 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
36520 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
36530 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
36540 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
36550 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
36560 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
36570 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
36580 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
36590 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
365a0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
365b0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
365c0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
365d0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
365e0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
365f0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
36600 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
36610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36620 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
36630 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
36640 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36650 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36660 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
36670 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
36680 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
36690 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
366a0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
366b0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
366c0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
366d0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
366e0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
366f0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
36700 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
36710 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
36720 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
36730 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
36740 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
36750 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
36760 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
36770 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
36780 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
36790 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
367a0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
367b0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
367c0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
367d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
367e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
367f0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
36800 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
36810 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
36820 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
36830 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
36840 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
36850 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
36860 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
36870 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65  e3_db_release_me
36880 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  mory()].*/.int s
36890 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
368a0 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
368b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 72 65  ** CAPI3REF: Fre
368c0 65 20 4d 65 6d 6f 72 79 20 55 73 65 64 20 42 79  e Memory Used By
368d0 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
368e0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
368f0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c  e sqlite3_db_rel
36900 65 61 73 65 5f 6d 65 6d 6f 72 79 28 44 29 20 69  ease_memory(D) i
36910 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
36920 73 20 74 6f 20 66 72 65 65 20 61 73 20 6d 75 63  s to free as muc
36930 68 20 68 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79  h heap.** memory
36940 20 61 73 20 70 6f 73 73 69 62 6c 65 20 66 72 6f   as possible fro
36950 6d 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  m database conne
36960 63 74 69 6f 6e 20 44 2e 20 55 6e 6c 69 6b 65 20  ction D. Unlike 
36970 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
36980 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36990 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 69  ] interface, thi
369a0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  s interface is e
369b0 66 66 65 63 74 20 65 76 65 6e 0a 2a 2a 20 77 68  ffect even.** wh
369c0 65 6e 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  en then [SQLITE_
369d0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
369e0 4e 41 47 45 4d 45 4e 54 5d 20 63 6f 6d 70 69 6c  NAGEMENT] compil
369f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
36a00 0a 2a 2a 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a  .** omitted..**.
36a10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
36a20 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
36a30 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  mory()].*/.int s
36a40 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73  qlite3_db_releas
36a50 65 5f 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65 33  e_memory(sqlite3
36a60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36a70 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
36a80 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
36a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36aa0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
36ab0 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  mit64() interfac
36ac0 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75  e sets and/or qu
36ad0 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66  eries the.** sof
36ae0 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61  t limit on the a
36af0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
36b00 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
36b10 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
36b20 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  Lite..** ^SQLite
36b30 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70   strives to keep
36b40 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69   heap memory uti
36b50 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74  lization below t
36b60 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20  he soft heap.** 
36b70 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e  limit by reducin
36b80 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  g the number of 
36b90 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68  pages held in th
36ba0 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20  e page cache.** 
36bb0 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75  as heap memory u
36bc0 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73  sages approaches
36bd0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
36be0 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
36bf0 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65  mit is "soft" be
36c00 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67  cause even thoug
36c10 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73  h SQLite strives
36c20 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f   to stay.** belo
36c30 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20  w the limit, it 
36c40 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20  will exceed the 
36c50 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61  limit rather tha
36c60 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e  n generate.** an
36c70 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
36c80 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72  error.  In other
36c90 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74   words, the soft
36ca0 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20   heap limit .** 
36cb0 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
36cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
36cd0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
36ce0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
36cf0 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68  _limit64() is th
36d00 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
36d10 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36d20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
36d30 6c 6c 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ll, or negative 
36d40 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  in the case of a
36d50 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66  n.** error.  ^If
36d60 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
36d70 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74  is negative.** t
36d80 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73  hen no change is
36d90 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66   made to the sof
36da0 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48  t heap limit.  H
36db0 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e  ence, the curren
36dc0 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
36dd0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
36de0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
36df0 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a  ed by invoking.*
36e00 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  * sqlite3_soft_h
36e10 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69  eap_limit64() wi
36e20 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72  th a negative ar
36e30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gument..**.** ^I
36e40 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
36e50 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68   is zero then th
36e60 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36e70 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  t is disabled..*
36e80 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20  *.** ^(The soft 
36e90 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f  heap limit is no
36ea0 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68  t enforced in th
36eb0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
36ec0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f  entation.** if o
36ed0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f  ne or more of fo
36ee0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f  llowing conditio
36ef0 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a  ns are true:.**.
36f00 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
36f10 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
36f20 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65  mit is set to ze
36f30 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f  ro..** <li> Memo
36f40 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73  ry accounting is
36f50 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
36f60 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
36f70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71   the.**      [sq
36f80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
36f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
36fa0 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61  STATUS],...) sta
36fb0 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61  rt-time option a
36fc0 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b  nd.**      the [
36fd0 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
36fe0 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c  EMSTATUS] compil
36ff0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
37000 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e  * <li> An altern
37010 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65  ative page cache
37020 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37030 69 73 20 73 70 65 63 69 66 69 65 64 20 75 73 69  is specified usi
37040 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  ng.**      [sqli
37050 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
37060 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
37070 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69  E2],...)..** <li
37080 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65  > The page cache
37090 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20   allocates from 
370a0 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70  its own memory p
370b0 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ool supplied.** 
370c0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
370d0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
370e0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
370f0 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74  E],...) rather t
37100 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d  han.**      from
37110 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f   the heap..** </
37120 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69  ul>)^.**.** Begi
37130 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
37140 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c  e version 3.7.3,
37150 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37160 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
37170 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
37180 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
37190 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
371a0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
371b0 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  EMENT].** compil
371c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
371d0 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20   invoked.  With 
371e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
371f0 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
37200 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68  ],.** the soft h
37210 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
37220 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d  orced on every m
37230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37240 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53  .  Without.** [S
37250 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
37260 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
37270 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37280 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66  imit is only enf
37290 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65  orced.** when me
372a0 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
372b0 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61  d by the page ca
372c0 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75  che.  Testing su
372d0 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61  ggests that beca
372e0 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20  use.** the page 
372f0 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65  cache is the pre
37300 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20  dominate memory 
37310 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20  user in SQLite, 
37320 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
37330 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76  ions will achiev
37340 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20  e adequate soft 
37350 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72  heap limit enfor
37360 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a  cement without.*
37370 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51  * the use of [SQ
37380 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37390 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
373a0 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d  **.** The circum
373b0 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68  stances under wh
373c0 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ich SQLite will 
373d0 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74  enforce the soft
373e0 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a   heap limit may.
373f0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75  ** changes in fu
37400 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
37410 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69   SQLite..*/.sqli
37420 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
37430 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37440 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64(sqlite3_int6
37450 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  4 N);../*.** CAP
37460 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
37470 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69  d Soft Heap Limi
37480 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44  t Interface.** D
37490 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
374a0 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65 63  This is a deprec
374b0 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  ated version of 
374c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  the [sqlite3_sof
374d0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
374e0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  ].** interface. 
374f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
37500 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69   provided for hi
37510 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
37520 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20  bility.** only. 
37530 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61   All new applica
37540 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65  tions should use
37550 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
37560 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
37570 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  64()] interface 
37580 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69 73  rather than this
37590 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   one..*/.SQLITE_
375a0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
375b0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
375c0 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
375d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
375e0 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
375f0 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
37600 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
37610 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
37620 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
37630 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
37640 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
37650 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
37660 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
37670 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
37680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37690 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
376a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
376b0 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
376c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
376d0 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
376e0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
376f0 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
37700 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
37710 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
37720 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
37730 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
37740 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
37750 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
37760 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
37770 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
37780 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
37790 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
377a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
377b0 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
377c0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
377d0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
377e0 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
377f0 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
37800 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
37810 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
37820 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
37830 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
37840 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
37850 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
37860 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
37870 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
37880 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
37890 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
378a0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
378b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
378c0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
378d0 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
378e0 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
378f0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
37900 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
37910 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
37920 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
37930 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
37940 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
37950 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
37960 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
37970 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
37980 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
37990 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
379a0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
379b0 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
379c0 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
379d0 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
379e0 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
379f0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
37a00 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
37a10 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
37a20 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
37a30 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
37a40 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
37a50 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
37a60 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
37a70 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
37a80 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
37a90 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
37aa0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
37ab0 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
37ac0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
37ad0 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
37ae0 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
37af0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
37b00 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
37b10 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
37b20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
37b30 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
37b40 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
37b50 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
37b60 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
37b70 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
37b80 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
37b90 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
37ba0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
37bb0 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
37bc0 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
37bd0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
37be0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
37bf0 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
37c00 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
37c10 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
37c20 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
37c30 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
37c40 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
37c50 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
37c60 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
37c70 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
37c80 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
37c90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
37ca0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
37cb0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
37cc0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
37cd0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
37ce0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
37cf0 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
37d00 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
37d10 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
37d20 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
37d30 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
37d40 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
37d50 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
37d60 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
37d70 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
37d80 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
37d90 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
37da0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
37db0 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
37dc0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
37dd0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
37de0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
37df0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
37e00 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
37e10 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
37e20 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
37e30 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
37e40 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
37e50 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
37e60 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
37e70 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
37e80 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
37e90 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
37ea0 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
37eb0 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
37ec0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
37ed0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
37ee0 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
37ef0 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
37f00 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
37f10 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
37f20 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
37f30 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
37f40 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
37f50 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
37f60 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
37f70 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
37f80 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
37f90 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
37fa0 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
37fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37fc0 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
37fd0 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
37fe0 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
37ff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
38000 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
38010 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
38020 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
38030 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
38040 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
38050 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
38060 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
38070 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
38080 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
38090 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
380a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
380b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
380c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
380d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
380e0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
380f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38100 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
38110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
38120 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
38130 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
38140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
38150 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
38160 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
38170 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
38180 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
38190 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
381a0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
381b0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
381c0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
381d0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
381e0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
381f0 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
38200 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
38210 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
38220 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
38230 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
38240 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
38250 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
38260 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
38270 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
38280 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
38290 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
382a0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
382b0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
382c0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
382d0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
382e0 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
382f0 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
38300 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
38310 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
38320 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
38330 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
38340 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   file..**.** ^Th
38350 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
38360 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
38370 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
38380 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69   load an.** SQLi
38390 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
383a0 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
383b0 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
383c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74  ..**.** ^The ent
383d0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
383e0 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79  c..** ^zProc may
383f0 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
38400 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
38410 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
38420 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20  .** defaults to 
38430 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
38440 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68  on_init"..** ^Th
38450 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
38460 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
38470 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
38480 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
38490 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
384a0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
384b0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
384c0 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  g..** ^If an err
384d0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
384e0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
384f0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71   then the.** [sq
38500 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
38510 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
38520 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
38530 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72  to.** fill *pzEr
38540 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
38550 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
38560 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
38570 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
38580 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
38590 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ]. The calling f
385a0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  unction.** shoul
385b0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
385c0 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
385d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
385e0 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
385f0 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
38600 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
38610 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  * [sqlite3_enabl
38620 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
38630 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  ()] prior to cal
38640 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a  ling this API,.*
38650 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  * otherwise an e
38660 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
38670 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
38680 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
38690 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
386a0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
386b0 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
386c0 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
386d0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
386e0 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
386f0 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
38700 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
38710 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
38720 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
38730 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
38740 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
38750 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
38760 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
38770 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
38780 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
38790 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
387a0 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
387b0 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
387c0 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
387d0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
387e0 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
387f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
38800 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
38810 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
38820 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
38830 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
38840 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
38850 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
38860 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat