/ Hex Artifact Content
Login

Artifact a7d351d5ae015179e7ef97a1060c7213b50efd9b:


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 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
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: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 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 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 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 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **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 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
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 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
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 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
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 34 3c 3c 38  TE_IOERR | (4<<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 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<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 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
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 36 3c 3c 38 29 29  _IOERR | (6<<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 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
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 37 3c 3c 38 29 29 0a  IOERR | (7<<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 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
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 38 3c 3c 38 29 29 0a 23  OERR | (8<<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 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
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 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<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 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
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 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7390: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
73a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
73b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4f 70 65 6e    int (*xShmOpen
73c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
73d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 53 69  ;.  int (*xShmSi
73e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
73f0: 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65 2c 20  *, int reqSize, 
7400: 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29 3b 0a  int *pNewSize);.
7410: 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65 74 29    int (*xShmGet)
7420: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7430: 69 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74  int reqSize, int
7440: 20 2a 70 53 69 7a 65 2c 20 76 6f 69 64 20 76 6f   *pSize, void vo
7450: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
7460: 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29 28   (*xShmRelease)(
7470: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7480: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
74a0: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
74b0: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
74c0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
74d0: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
74e0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
74f0: 53 68 6d 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  ShmClose)(sqlite
7500: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
7510: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
7520: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
7530: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
7540: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
7550: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
7560: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
7570: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
7580: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7590: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
75a0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
75b0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
75c0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
75d0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
75e0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
75f0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
7600: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7620: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
7630: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7640: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
7650: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
7660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7670: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
7680: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
7690: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
76a0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
76b0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
76c0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
76d0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
76e0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
76f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7700: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7710: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7720: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7730: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
7740: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7750: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
7760: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
7770: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
7780: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
7790: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
77a0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
77b0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
77c0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
77d0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
77e0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
77f0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
7800: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
7810: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7820: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
7830: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
7840: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
7850: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
7860: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
7870: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
7880: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
7890: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
78a0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
78b0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
78c0: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
78d0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
78e0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
78f0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
7900: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
7910: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
7920: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
7930: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
7940: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
7950: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
7960: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
7970: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
7980: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
7990: 73 74 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ster..*/.#define
79a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
79b0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
79c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
79d0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
79e0: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
79f0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
7a00: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
7a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7a20: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
7a30: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
7a40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
7a50: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35  ZE_HINT        5
7a60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7a70: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
7a80: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
7a90: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
7aa0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
7ab0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
7ac0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
7ad0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
7ae0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
7af0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
7b00: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
7b10: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
7b20: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
7b30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
7b40: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
7b50: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
7b60: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
7b70: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
7b80: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
7b90: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
7ba0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
7bb0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
7bc0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7bd0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
7be0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
7bf0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7c00: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
7c10: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
7c20: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7c30: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7c40: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
7c50: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
7c60: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
7c70: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
7c80: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
7c90: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
7ca0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
7cb0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
7cc0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
7cd0: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
7ce0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
7cf0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
7d00: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
7d10: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
7d20: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
7d30: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
7d40: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
7d50: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
7d60: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
7d70: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
7d80: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
7d90: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
7da0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
7db0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
7dc0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7dd0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
7de0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
7df0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
7e00: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
7e10: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
7e20: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
7e30: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
7e40: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
7e50: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
7e60: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
7e70: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
7e80: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
7e90: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
7ea0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
7eb0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
7ec0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
7ed0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
7ee0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
7ef0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
7f00: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
7f10: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
7f20: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
7f30: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
7f40: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7f50: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7f60: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7f70: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7f80: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
7f90: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
7fa0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
7fb0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
7fc0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7fd0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7fe0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
7ff0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
8000: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
8010: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
8020: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
8030: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
8040: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
8050: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
8060: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
8070: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
8080: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
8090: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
80a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
80b0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
80c0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
80d0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
80e0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
80f0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
8100: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
8110: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
8120: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
8130: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
8140: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
8150: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
8160: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
8170: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
8180: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
8190: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
81a0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
81b0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
81c0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
81d0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
81e0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
81f0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  les..**.** SQLit
8200: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
8210: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
8220: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8230: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
8240: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
8250: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
8260: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
8270: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
8280: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
8290: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
82a0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
82b0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
82c0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
82d0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
82e0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
82f0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
8300: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
8310: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
8320: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
8330: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
8340: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
8350: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
8360: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
8370: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
8380: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
8390: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
83a0: 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  is xOpen is a NU
83b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
83c0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
83d0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
83e0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
83f0: 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65  the file.  Whene
8400: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
8410: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8420: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
8430: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
8440: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
8450: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
8460: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
8470: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8480: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
8490: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
84a0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
84b0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
84c0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
84d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
84e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
84f0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8500: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8520: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8530: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
8540: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
8550: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
8560: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
8570: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
8580: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
8590: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
85a0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
85b0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
85c0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
85d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
85e0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
85f0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
8600: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69   set..**.** SQLi
8610: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
8620: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
8630: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
8640: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
8650: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
8660: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
8670: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
8680: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
8690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
86a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
86c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
86d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
86e0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
86f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8700: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8710: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8720: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8730: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8740: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
8750: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8760: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8770: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  URNAL].** </ul>.
8780: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
8790: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
87a0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
87b0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
87c0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
87d0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
87e0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
87f0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
8800: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
8810: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
8820: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
8830: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
8840: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
8850: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
8860: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
8870: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
8880: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
8890: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
88a0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
88b0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
88c0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
88d0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
88e0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
88f0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
8900: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
8910: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8920: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
8930: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
8940: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
8950: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
8960: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
8970: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
8980: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
8990: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
89a0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
89b0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
89c0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
89d0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
89e0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
89f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8a00: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
8a10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8a20: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
8a30: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8a40: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8a50: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
8a60: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
8a70: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
8a80: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
8a90: 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b  s closed.  The [
8aa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8ab0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
8ac0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
8ad0: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
8ae0: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
8af0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
8b00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8b10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
8b20: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
8b30: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
8b40: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
8b50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8b60: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
8b70: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
8b80: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
8b90: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
8ba0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
8bb0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
8bc0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
8bd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8be0: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
8bf0: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
8c00: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
8c10: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
8c20: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
8c30: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
8c40: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
8c50: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
8c60: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
8c70: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
8c80: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
8c90: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
8ca0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
8cb0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
8cc0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8cd0: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
8ce0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
8cf0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
8d00: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
8d10: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
8d20: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
8d30: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
8d40: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
8d50: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
8d60: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
8d70: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
8d80: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
8d90: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
8da0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
8db0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
8dc0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
8dd0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
8de0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
8df0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
8e00: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
8e10: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
8e20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8e30: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
8e40: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
8e50: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
8e60: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
8e70: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
8e80: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
8e90: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
8ea0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
8eb0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
8ec0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
8ed0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
8ee0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
8ef0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
8f00: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
8f10: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8f20: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
8f30: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
8f40: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
8f50: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
8f60: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
8f70: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
8f80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8f90: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
8fa0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
8fb0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8fc0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
8fd0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
8fe0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
8ff0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
9000: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
9010: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
9020: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
9030: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
9040: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
9050: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
9060: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
9070: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9080: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9090: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
90a0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
90b0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
90c0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
90d0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
90e0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
90f0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9100: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9110: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
9120: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
9130: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
9140: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
9150: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
9160: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
9170: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9180: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9190: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
91a0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
91b0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
91c0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
91d0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
91e0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
91f0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9200: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
9210: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
9220: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
9230: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
9240: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
9250: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
9260: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
9270: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
9280: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
9290: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
92a0: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
92b0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
92c0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
92d0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
92e0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
92f0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
9300: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
9310: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
9320: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
9330: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
9340: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
9350: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
9360: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
9370: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
9380: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
9390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
93a0: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
93b0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
93c0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
93d0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
93e0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
93f0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
9400: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a  and time..**.*/.
9410: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
9420: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
9430: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
9440: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9450: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9460: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9470: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9480: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9490: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
94a0: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
94b0: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
94c0: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
94d0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
94e0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
94f0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
9500: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
9510: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
9520: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
9530: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
9540: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9550: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9560: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9570: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9580: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9590: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
95a0: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
95b0: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
95c0: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
95d0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
95e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
95f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9600: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
9610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
9620: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
9630: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
9640: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9650: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9660: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9670: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9680: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9690: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
96a0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
96b0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
96c0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
96d0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
96e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
96f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
9700: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
9710: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
9720: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
9730: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9740: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9750: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9760: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9770: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9780: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9790: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
97a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
97b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
97c0: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
97d0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
97e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
97f0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
9800: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
9810: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
9820: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
9830: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
9840: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9850: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9860: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9870: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9880: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9890: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
98a0: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
98b0: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
98c0: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
98d0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
98e0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
98f0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
9900: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
9910: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
9920: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
9930: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
9940: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9950: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e   */.  int (*xRen
9960: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9970: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9980: 4f 6c 64 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Old, const char 
9990: 2a 7a 4e 65 77 2c 20 69 6e 74 20 64 69 72 53 79  *zNew, int dirSy
99a0: 6e 63 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  nc);.  int (*xCu
99b0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
99c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
99d0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
99e0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
99f0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
9a00: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
9a10: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
9a20: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
9a30: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
9a40: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
9a50: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
9a60: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
9a70: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
9a80: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
9a90: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
9aa0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
9ab0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9ac0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
9ad0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
9ae0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
9af0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
9b00: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
9b10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
9b20: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
9b30: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
9b40: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
9b50: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
9b60: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
9b70: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
9b80: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
9b90: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
9ba0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9bb0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
9bc0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9bd0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
9be0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
9bf0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
9c00: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
9c10: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
9c20: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9c30: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9c40: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74   the file is bot
9c50: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
9c60: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68  ritable..** With
9c70: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9c80: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
9c90: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
9ca0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
9cb0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
9cc0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9cd0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
9ce0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
9cf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9d00: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
9d10: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9d20: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
9d30: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
9d40: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
9d50: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
9d60: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
9d70: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
9d80: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
9d90: 6b 69 6e 67 20 73 74 61 74 65 73 20 74 68 61 74  king states that
9da0: 0a 2a 2a 20 61 6e 20 73 71 6c 69 74 65 33 5f 73  .** an sqlite3_s
9db0: 68 6d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  hm object can be
9dc0: 20 69 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20   in..*/.#define 
9dd0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
9de0: 4b 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e  K       0.#defin
9df0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41  e SQLITE_SHM_REA
9e00: 44 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  D         1.#def
9e10: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52  ine SQLITE_SHM_R
9e20: 45 41 44 5f 46 55 4c 4c 20 20 20 20 32 0a 23 64  EAD_FULL    2.#d
9e30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
9e40: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 33 0a  _WRITE        3.
9e50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9e60: 48 4d 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  HM_PENDING      
9e70: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
9e80: 5f 53 48 4d 5f 43 48 45 43 4b 50 4f 49 4e 54 20  _SHM_CHECKPOINT 
9e90: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
9ea0: 54 45 5f 53 48 4d 5f 52 45 43 4f 56 45 52 20 20  TE_SHM_RECOVER  
9eb0: 20 20 20 20 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      6../*.** CAP
9ec0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
9ed0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
9ee0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
9ef0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9f00: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
9f10: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
9f20: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
9f30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
9f40: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
9f50: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
9f60: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
9f70: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
9f80: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
9f90: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
9fa0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
9fb0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
9fc0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
9fd0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
9fe0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
9ff0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
a000: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
a010: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
a020: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
a030: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
a040: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
a050: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
a060: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
a070: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
a080: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
a090: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
a0a0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
a0b0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
a0c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
a0d0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
a0e0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
a0f0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
a100: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
a110: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
a120: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a130: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
a140: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
a150: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
a160: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
a170: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
a180: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
a190: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
a1a0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
a1b0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
a1c0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
a1d0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
a1e0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
a1f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a200: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
a210: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
a220: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
a230: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a240: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
a250: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
a260: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
a270: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
a280: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
a290: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a2a0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
a2b0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
a2c0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
a2d0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
a2e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
a2f0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
a300: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
a310: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a320: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a330: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
a340: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a350: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
a360: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
a370: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
a380: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
a390: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
a3a0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
a3b0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
a3c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
a3d0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
a3e0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
a3f0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
a400: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
a410: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
a420: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
a430: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
a440: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
a450: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
a460: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
a470: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
a480: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
a490: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
a4a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
a4b0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
a4c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
a4d0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
a4e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
a4f0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
a500: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
a510: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
a520: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
a530: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a540: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
a550: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
a560: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
a570: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
a580: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
a590: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
a5a0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
a5b0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
a5c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
a5d0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
a5e0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
a5f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a600: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
a610: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
a620: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
a630: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
a640: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
a650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
a660: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
a670: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
a680: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a690: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
a6a0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
a6b0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
a6c0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
a6d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
a6e0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
a6f0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
a700: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
a710: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
a720: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
a730: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
a740: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
a750: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
a760: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
a770: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
a780: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
a790: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
a7a0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
a7b0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
a7c0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
a7d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
a7e0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
a7f0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
a800: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
a810: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
a820: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
a830: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
a840: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
a850: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a860: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
a870: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
a880: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
a890: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
a8a0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
a8b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a8c0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
a8d0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
a8e0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
a8f0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
a900: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
a910: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
a920: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
a930: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
a940: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
a950: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
a960: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
a970: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
a980: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
a990: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
a9a0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
a9b0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
a9c0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
a9d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
a9e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a9f0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
aa00: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
aa10: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
aa20: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
aa30: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
aa40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
aa50: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
aa60: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
aa70: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
aa80: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
aa90: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
aaa0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
aab0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
aac0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
aad0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
aae0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
aaf0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
ab00: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
ab10: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
ab20: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
ab30: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
ab40: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
ab50: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
ab60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
ab70: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
ab80: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
ab90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
aba0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
abb0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
abc0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
abd0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
abe0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
abf0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
ac00: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
ac10: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
ac20: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
ac30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
ac40: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
ac50: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
ac60: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
ac70: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
ac80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ac90: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
aca0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
acb0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
acc0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
acd0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
ace0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
acf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ad00: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
ad10: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
ad20: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
ad30: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
ad40: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
ad50: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
ad60: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
ad70: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
ad80: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
ad90: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
ada0: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
adb0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
adc0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
add0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
ade0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
adf0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
ae00: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
ae10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
ae20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ae30: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
ae40: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
ae50: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
ae60: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ae70: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
ae80: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
ae90: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
aea0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
aeb0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
aec0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
aed0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
aee0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
aef0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
af00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
af10: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
af20: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
af30: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
af40: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
af50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
af60: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
af70: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
af80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
af90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
afa0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
afb0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
afc0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
afd0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
afe0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
aff0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
b000: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
b010: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
b020: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
b030: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
b040: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
b050: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
b060: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
b070: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
b080: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
b090: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
b0a0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
b0b0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
b0c0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
b0d0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
b0e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b0f0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
b100: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
b110: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
b120: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
b130: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
b140: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
b150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
b160: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
b170: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
b180: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
b190: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
b1a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
b1b0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
b1c0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
b1d0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
b1e0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
b1f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b200: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
b210: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
b220: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
b230: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
b240: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
b250: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
b260: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
b270: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
b280: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b290: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
b2a0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
b2b0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
b2c0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
b2d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
b2e0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
b2f0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
b300: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
b310: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
b320: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
b330: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
b340: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
b350: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
b360: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
b370: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
b380: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
b390: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
b3a0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
b3b0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
b3c0: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
b3d0: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
b3e0: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
b3f0: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
b400: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
b410: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53  ending on the [S
b420: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
b430: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
b440: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
b450: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
b460: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
b470: 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
b480: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
b490: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
b4a0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
b4b0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
b4c0: 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
b4d0: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
b4e0: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
b4f0: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
b500: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
b510: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
b520: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
b530: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
b540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
b550: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
b560: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
b570: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b580: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
b590: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b5a0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
b5b0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
b5c0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
b5d0: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
b5e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b5f0: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
b600: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
b610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
b620: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
b630: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
b640: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
b650: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
b660: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
b670: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
b680: 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68  t argument).  Th
b690: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f  e.** sqlite3_db_
b6a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
b6b0: 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62  ce should only b
b6c0: 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65  e used immediate
b6d0: 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20  ly after.** the 
b6e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b6f0: 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75  ion is created u
b700: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
b710: 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  en()],.** [sqlit
b720: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
b730: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b740: 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  2()].  .**.** Th
b750: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b760: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
b770: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
b780: 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69   is the.** confi
b790: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20  guration verb - 
b7a0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
b7b0: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
b7c0: 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66  hat.** aspect of
b7d0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
b7e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
b7f0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
b800: 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69  ** The only choi
b810: 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75  ce for this valu
b820: 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43  e is [SQLITE_DBC
b830: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
b840: 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61  ..** New verbs a
b850: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  re likely to be 
b860: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
b870: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
b880: 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  te..** Additiona
b890: 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65  l arguments depe
b8a0: 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a  nd on the verb..
b8b0: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
b8c0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b8d0: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
b8e0: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
b8f0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
b900: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
b910: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
b920: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b930: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
b940: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
b950: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
b960: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
b970: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
b980: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b990: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b9a0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b9b0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
b9c0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
b9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b9e0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
b9f0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
ba00: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
ba10: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
ba20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
ba30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
ba40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ba50: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
ba60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ba70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ba80: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
ba90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
baa0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
bab0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
bac0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bad0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
bae0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
baf0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
bb00: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
bb10: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
bb20: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
bb30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
bb40: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
bb50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
bb60: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
bb70: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
bb80: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
bb90: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
bba0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
bbb0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
bbc0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
bbd0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
bbe0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
bbf0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
bc00: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
bc10: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
bc20: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
bc30: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
bc40: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
bc50: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
bc60: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
bc70: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
bc80: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
bc90: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
bca0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
bcb0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
bcc0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
bcd0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
bce0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
bcf0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
bd00: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
bd10: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
bd20: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
bd30: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
bd40: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
bd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
bd60: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
bd70: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
bd80: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
bd90: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
bda0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
bdb0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
bdc0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
bdd0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
bde0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
bdf0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
be00: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
be10: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
be20: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
be30: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
be40: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
be50: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
be60: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
be70: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
be80: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
be90: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
bea0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
beb0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
bec0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
bed0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
bee0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
bef0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
bf00: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
bf10: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
bf20: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
bf30: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
bf40: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
bf50: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
bf60: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
bf70: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
bf80: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
bf90: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
bfa0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
bfb0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
bfc0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
bfd0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
bfe0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
bff0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
c000: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
c010: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
c020: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
c030: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
c040: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
c050: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
c060: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
c070: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
c080: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
c090: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
c0a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c0b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
c0c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
c0d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
c0e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
c0f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
c100: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
c110: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
c120: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
c130: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
c140: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
c150: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
c160: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
c170: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
c180: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
c190: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
c1a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
c1b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
c1c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
c1d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
c1e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c1f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
c200: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
c210: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
c220: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
c230: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
c240: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
c250: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
c260: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
c270: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
c280: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
c290: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
c2a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
c2b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
c2c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
c2d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
c2e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
c2f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
c300: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
c310: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c320: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
c330: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
c340: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
c350: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c360: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
c370: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
c380: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
c390: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
c3a0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
c3b0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
c3c0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
c3d0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
c3e0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
c3f0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
c400: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
c410: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
c420: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
c430: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
c440: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
c450: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
c460: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
c470: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
c480: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
c490: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
c4a0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
c4b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
c4c0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
c4d0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
c4e0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
c4f0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
c500: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
c510: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
c520: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
c530: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
c540: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
c550: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
c560: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
c570: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
c580: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
c590: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
c5a0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
c5b0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
c5c0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
c5d0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
c5e0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
c5f0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c600: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
c610: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c620: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
c630: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
c640: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
c650: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
c660: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
c670: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
c680: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
c690: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
c6a0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
c6b0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
c6c0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
c6d0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
c6e0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
c6f0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
c700: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
c710: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
c720: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
c730: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
c740: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
c750: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
c760: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
c770: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
c780: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
c790: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c7a0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
c7b0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
c7c0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c7d0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
c7e0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
c7f0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
c800: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
c810: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
c820: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
c830: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
c840: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
c850: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
c860: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
c870: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
c880: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
c890: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
c8a0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c8b0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
c8c0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
c8d0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
c8e0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
c8f0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
c900: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
c910: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
c920: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
c930: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
c940: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
c950: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
c960: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
c970: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
c980: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
c990: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
c9a0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
c9b0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
c9c0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
c9d0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
c9e0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
c9f0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
ca00: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
ca10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
ca20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
ca30: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
ca40: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
ca50: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
ca60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca70: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
ca80: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
ca90: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
caa0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
cab0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
cac0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
cad0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cae0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
caf0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
cb00: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
cb10: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
cb20: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cb30: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
cb40: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
cb50: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
cb60: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
cb70: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
cb80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
cb90: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
cba0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
cbb0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
cbc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
cbd0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
cbe0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
cbf0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
cc00: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
cc10: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
cc20: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cc30: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
cc40: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
cc50: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
cc60: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
cc70: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
cc80: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
cc90: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
cca0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
ccb0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
ccc0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
ccd0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
cce0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
ccf0: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
cd00: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
cd10: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
cd20: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
cd30: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
cd40: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
cd50: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
cd60: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
cd70: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
cd80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
cd90: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
cda0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
cdb0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
cdc0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
cdd0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
cde0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
cdf0: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
ce00: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
ce10: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
ce20: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
ce30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
ce40: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
ce50: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
ce60: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
ce70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ce80: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
ce90: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cea0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
ceb0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
cec0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
ced0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
cee0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
cef0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
cf00: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
cf10: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
cf20: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
cf30: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
cf40: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
cf50: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
cf60: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
cf70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
cf80: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
cf90: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
cfa0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
cfb0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
cfc0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
cfd0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
cfe0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cff0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d000: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d010: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d020: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d030: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d040: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d050: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d060: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d070: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d080: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d090: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d0a0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d0b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d0c0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d0d0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
d0e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
d0f0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
d100: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
d110: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d120: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
d130: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
d140: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
d150: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
d160: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
d170: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
d180: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
d190: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
d1a0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
d1b0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
d1c0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
d1d0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
d1e0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d1f0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d200: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d210: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
d220: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
d230: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
d240: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
d250: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
d260: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
d270: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
d280: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
d290: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
d2a0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
d2b0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
d2c0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
d2d0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
d2e0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
d2f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
d300: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
d310: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
d320: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
d330: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
d340: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
d350: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
d360: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
d370: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
d380: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
d390: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
d3a0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
d3b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d3c0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
d3d0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
d3e0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
d3f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
d400: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
d410: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
d420: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
d430: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
d440: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
d450: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
d460: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
d470: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
d480: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
d490: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
d4a0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
d4b0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
d4c0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
d4d0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
d4e0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
d4f0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
d500: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
d510: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
d520: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
d530: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
d540: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d550: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d560: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
d570: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
d580: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d590: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
d5a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d5b0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
d5c0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
d5d0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
d5e0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
d5f0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
d600: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
d610: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
d620: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
d630: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
d640: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
d650: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
d660: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
d670: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d680: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
d690: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
d6a0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d6b0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
d6c0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
d6d0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
d6e0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
d6f0: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
d700: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
d710: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d720: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
d730: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
d740: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d750: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
d760: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d770: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
d780: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
d790: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
d7a0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d7b0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d7c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d7d0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
d7e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
d7f0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d800: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
d810: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
d820: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
d830: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
d840: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
d850: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
d860: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
d870: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
d880: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
d890: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
d8a0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
d8b0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
d8c0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
d8d0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
d8e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d8f0: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
d900: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
d910: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
d920: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
d930: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d940: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
d950: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
d960: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
d970: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
d980: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
d990: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
d9a0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
d9b0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
d9c0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
d9d0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
d9e0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
d9f0: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
da00: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
da10: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
da20: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
da30: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
da40: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
da50: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
da60: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
da70: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
da80: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
da90: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
daa0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
dab0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
dac0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
dad0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
dae0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
daf0: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
db00: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
db10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
db20: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
db30: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
db40: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
db50: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
db60: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
db70: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
db80: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
db90: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
dba0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
dbb0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
dbc0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
dbd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dbe0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
dbf0: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
dc00: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
dc10: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
dc20: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
dc30: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
dc40: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
dc50: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
dc60: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
dc70: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
dc80: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
dc90: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
dca0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63   which the scrac
dcb0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
dcc0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
dcd0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
dce0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
dcf0: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
dd00: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
dd10: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
dd20: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
dd30: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
dd40: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
dd50: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
dd60: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
dd70: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
dd80: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
dd90: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
dda0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
ddb0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74  uired due to int
ddc0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
ddd0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
dde0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
ddf0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
de00: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
de10: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
de20: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
de30: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
de40: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
de50: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
de60: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72  ratch buffer per
de70: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
de80: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
de90: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
dea0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
deb0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c  f threads.  ^SQL
dec0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
ded0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
dee0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
def0: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74  is more than 6 t
df00: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
df10: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20  e.** page size. 
df20: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
df30: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
df40: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  l scratch memory
df50: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74   beyond .** what
df60: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
df70: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
df80: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
df90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
dfa0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
dfb0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
dfc0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
dfd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dfe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
dff0: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
e000: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
e010: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
e020: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
e030: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
e040: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
e050: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
e060: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
e070: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
e080: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e  e implemenation.
e090: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
e0a0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
e0b0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
e0c0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
e0d0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
e0e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e0f0: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
e100: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
e110: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
e120: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
e130: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
e140: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
e150: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
e160: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
e170: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
e180: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
e190: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
e1a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
e1b0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
e1c0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
e1d0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
e1e0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
e1f0: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
e200: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
e210: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
e220: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
e230: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
e240: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
e250: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
e260: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
e270: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
e280: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
e290: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
e2a0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
e2b0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
e2c0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
e2d0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
e2e0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
e2f0: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
e300: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
e310: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
e320: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
e330: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
e340: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
e350: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e360: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
e370: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
e380: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
e390: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
e3a0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
e3b0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
e3c0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
e3d0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
e3e0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
e3f0: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
e400: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
e410: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
e420: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
e430: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
e440: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
e450: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
e460: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
e470: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  space..** ^The i
e480: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
e490: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
e4a0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
e4b0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
e4c0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
e4d0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
e4e0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
e4f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e500: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
e510: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
e520: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
e530: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
e540: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
e550: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
e560: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
e570: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
e580: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
e590: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
e5a0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
e5b0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
e5c0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
e5d0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
e5e0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
e5f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e600: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
e610: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
e620: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
e630: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
e640: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
e650: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
e660: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e670: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
e680: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
e690: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
e6a0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
e6b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
e6c0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
e6d0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
e6e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
e6f0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
e700: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
e710: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
e720: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
e730: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
e740: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
e750: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
e760: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
e770: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
e780: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
e790: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
e7a0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
e7b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e7c0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
e7d0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
e7e0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
e7f0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
e800: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
e810: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
e820: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
e830: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
e840: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
e850: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
e860: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
e870: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
e880: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
e890: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
e8a0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
e8b0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
e8c0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
e8d0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
e8e0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
e8f0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
e900: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
e910: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
e920: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
e930: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e940: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
e950: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e960: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e970: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e980: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e990: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e9a0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e9b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e9c0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
e9d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
e9e0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
e9f0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
ea00: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
ea10: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
ea20: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
ea30: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
ea40: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
ea50: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
ea60: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
ea70: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
ea80: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
ea90: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
eaa0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
eab0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
eac0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
ead0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
eae0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
eaf0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
eb00: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
eb10: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
eb20: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
eb30: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
eb40: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
eb50: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
eb60: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
eb70: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
eb80: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
eb90: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
eba0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
ebb0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
ebc0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
ebd0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
ebe0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
ebf0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
ec00: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
ec10: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
ec20: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
ec30: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
ec40: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
ec50: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
ec60: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ec70: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
ec80: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
ec90: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
eca0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ecb0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
ecc0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
ecd0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
ece0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
ecf0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
ed00: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
ed10: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
ed20: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
ed30: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
ed40: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
ed50: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
ed60: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
ed70: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
ed80: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
ed90: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
eda0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
edb0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
edc0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
edd0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
ede0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
edf0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ee00: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
ee10: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
ee20: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
ee30: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
ee40: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
ee50: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
ee60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ee70: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
ee80: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
ee90: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
eea0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
eeb0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
eec0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
eed0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
eee0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
eef0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
ef00: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
ef10: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
ef20: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
ef30: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
ef40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
ef50: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
ef60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
ef70: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
ef80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
ef90: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
efa0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
efb0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
efc0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
efd0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
efe0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
eff0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
f000: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
f010: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f020: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
f030: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
f040: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
f050: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
f060: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
f070: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
f080: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
f090: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
f0a0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
f0b0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
f0c0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
f0d0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
f0e0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
f0f0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
f100: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
f110: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
f120: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f130: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f140: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f150: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
f160: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
f170: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
f180: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
f190: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
f1a0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
f1b0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
f1c0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
f1d0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
f1e0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
f1f0: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
f200: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
f210: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
f220: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
f230: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f240: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
f250: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
f260: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
f270: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
f280: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
f290: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
f2a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
f2b0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
f2c0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
f2d0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
f2e0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
f2f0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
f300: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
f310: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
f320: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f330: 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
f340: 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
f350: 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
f360: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
f370: 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
f380: 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
f390: 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
f3a0: 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
f3b0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
f3c0: 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
f3d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
f3e0: 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
f3f0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
f400: 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
f410: 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
f420: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
f430: 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
f440: 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
f450: 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
f460: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
f470: 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
f480: 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
f490: 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
f4a0: 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
f4b0: 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
f4c0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f4d0: 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
f4e0: 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
f4f0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
f500: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
f510: 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
f520: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
f530: 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
f540: 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
f550: 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
f560: 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
f570: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
f580: 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
f590: 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
f5a0: 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
f5b0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
f5c0: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
f5d0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
f5e0: 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
f5f0: 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
f600: 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
f610: 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
f620: 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
f630: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
f640: 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
f650: 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
f660: 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
f670: 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
f680: 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
f690: 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
f6a0: 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
f6b0: 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
f6c0: 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
f6d0: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
f6e0: 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
f6f0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
f700: 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
f710: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
f720: 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
f730: 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
f740: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
f750: 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
f760: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
f770: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
f780: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
f790: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
f7a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
f7b0: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
f7c0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
f7d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
f7e0: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
f7f0: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
f800: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
f810: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
f820: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
f830: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f840: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
f850: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
f860: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f870: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f880: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
f890: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
f8a0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f8c0: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
f8d0: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
f8e0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
f8f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f900: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
f910: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
f920: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
f930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f940: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
f950: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
f960: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
f970: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
f980: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f990: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
f9a0: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
f9b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f9c0: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
f9d0: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
f9e0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
f9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fa00: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
fa10: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
fa20: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
fa30: 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
fa40: 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
fa50: 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
fa60: 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
fa70: 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
fa80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fa90: 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
faa0: 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
fab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
fac0: 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
fad0: 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
fae0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
faf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fb00: 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
fb10: 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
fb20: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
fb30: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
fb40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
fb50: 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
fb60: 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
fb70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fb80: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
fb90: 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
fba0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
fbb0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
fbc0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
fbd0: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
fbe0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fbf0: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
fc00: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
fc10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
fc20: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
fc30: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
fc40: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
fc50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
fc60: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
fc70: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
fc80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
fc90: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
fca0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fcb0: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
fcc0: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
fcd0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
fce0: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
fcf0: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
fd00: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fd10: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
fd20: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
fd30: 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
fd40: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fd50: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
fd60: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
fd70: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
fd80: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
fd90: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
fda0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
fdb0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
fdc0: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
fdd0: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
fde0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fdf0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
fe00: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
fe10: 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
fe20: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
fe30: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
fe40: 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
fe50: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
fe60: 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
fe70: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
fe80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fe90: 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
fea0: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
feb0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
fec0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
fed0: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
fee0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
fef0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
ff00: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
ff10: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
ff20: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ff30: 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
ff40: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ff50: 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
ff60: 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
ff70: 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
ff80: 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
ff90: 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
ffa0: 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
ffb0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ffc0: 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
ffd0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
ffe0: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
fff0: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
10000 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
10010 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
10020 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
10030 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
10040 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
10050 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
10060 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
10070 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
10080 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
10090 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
100a0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
100b0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
100c0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
100d0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
100e0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
100f0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
10100 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
10110 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10120 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
10130 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
10140 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
10150 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
10160 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
10170 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  ller.** multiple
10180 20 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f   of 8.  See also
10190 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  : [SQLITE_CONFIG
101a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e  _LOOKASIDE]</dd>
101b0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
101c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
101d0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
101e0 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
101f0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
10200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10210 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
10220 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
10230 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
10240 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
10250 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10260 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
10270 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10280 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
10290 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
102a0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
102b0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
102c0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
102d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
102e0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
102f0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
10300 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
10310 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10320 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
10330 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
10340 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10350 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
10360 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
10370 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
10380 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
10390 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
103a0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
103b0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
103c0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
103d0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
103e0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
103f0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
10400 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
10410 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
10420 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
10430 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
10440 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
10450 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
10460 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
10470 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
10480 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
10490 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
104a0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
104b0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
104c0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
104d0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
104e0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
104f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10500 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
10510 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
10520 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
10530 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
10540 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
10550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10560 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
10570 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10580 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
10590 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
105a0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
105b0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
105c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
105d0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
105e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
105f0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
10600 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
10610 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
10620 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
10630 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
10640 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
10650 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
10660 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
10670 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
10680 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
10690 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
106a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
106b0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
106c0 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
106d0 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
106e0 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
106f0 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
10700 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
10710 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
10720 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
10730 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
10740 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
10750 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
10760 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
10770 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
10780 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
10790 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
107a0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
107b0 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
107c0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
107d0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
107e0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
107f0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
10800 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
10810 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
10820 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
10830 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
10840 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
10850 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
10860 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
10870 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
10880 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
10890 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
108a0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
108b0 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
108c0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
108d0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
108e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
108f0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
10900 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
10910 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
10920 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
10930 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
10940 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
10950 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
10960 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
10970 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
10980 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
10990 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
109a0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
109b0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
109c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
109d0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
109e0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
109f0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
10a00 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
10a10 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
10a20 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
10a30 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
10a40 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
10a50 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
10a60 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
10a70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
10a80 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
10a90 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10aa0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
10ab0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
10ac0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
10ad0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10ae0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
10af0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10b00 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
10b10 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
10b20 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
10b30 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
10b40 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
10b50 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
10b60 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
10b70 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
10b80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
10b90 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
10ba0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
10bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10bc0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
10bd0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
10be0 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
10bf0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10c00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
10c10 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
10c20 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
10c30 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
10c40 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
10c50 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
10c60 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
10c70 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
10c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10c90 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
10ca0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
10cb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
10cc0 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
10cd0 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
10ce0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
10cf0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
10d00 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
10d10 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
10d20 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
10d30 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
10d40 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
10d50 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
10d60 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
10d70 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
10d80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
10d90 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
10da0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
10db0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
10dc0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
10dd0 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
10de0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
10df0 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
10e00 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
10e10 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
10e20 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
10e30 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
10e40 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
10e50 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
10e60 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
10e70 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
10e80 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
10e90 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
10ea0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
10eb0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
10ec0 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
10ed0 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
10ee0 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
10ef0 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
10f00 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
10f10 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
10f20 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
10f30 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
10f40 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
10f50 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
10f60 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
10f70 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
10f80 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
10f90 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
10fa0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
10fb0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
10fc0 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
10fd0 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
10fe0 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
10ff0 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
11000 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
11010 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
11020 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
11030 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
11040 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
11050 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
11060 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
11070 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
11080 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
11090 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
110a0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
110b0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
110c0 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
110d0 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
110e0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
110f0 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
11100 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
11110 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
11120 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
11130 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
11140 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
11150 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
11160 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
11170 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
11180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
11190 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
111a0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
111b0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
111c0 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
111d0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
111e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
111f0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
11200 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
11210 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11220 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11230 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
11240 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
11250 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
11270 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
11280 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
11290 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
112a0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
112b0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
112c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
112d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
112e0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
112f0 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
11300 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
11310 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
11320 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
11330 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
11340 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
11350 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
11360 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
11370 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
11380 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
11390 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
113a0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
113b0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
113c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
113d0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
113e0 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
113f0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
11400 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
11410 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11420 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
11430 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
11440 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
11450 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
11460 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
11470 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
11480 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11490 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
114a0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
114b0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
114c0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
114d0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
114e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
114f0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
11500 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
11510 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
11520 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
11530 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
11540 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
11550 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
11560 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
11570 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11580 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
11590 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
115a0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
115b0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
115c0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
115d0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
115e0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
115f0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11600 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
11610 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
11620 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
11630 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
11640 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
11650 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
11660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11670 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
11680 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
11690 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
116a0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
116b0 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
116c0 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
116d0 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
116e0 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
116f0 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
11700 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
11710 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11720 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
11730 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
11740 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
11750 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
11760 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
11770 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
11780 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
11790 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
117a0 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
117b0 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
117c0 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
117d0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
117e0 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
117f0 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
11800 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
11810 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
11820 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
11830 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
11840 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
11850 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
11860 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
11870 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
11880 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
11890 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
118a0 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
118b0 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
118c0 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
118d0 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
118e0 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
118f0 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
11900 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
11910 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
11920 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
11930 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
11940 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
11950 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
11960 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
11970 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
11980 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
11990 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
119a0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
119b0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
119c0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
119d0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
119e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
119f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11a00 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
11a10 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
11a20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
11a30 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
11a40 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
11a50 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
11a60 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
11a70 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
11a80 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
11a90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11aa0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
11ab0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
11ac0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11ad0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11ae0 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11af0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11b00 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11b10 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11b20 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11b30 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11b40 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11b50 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
11b60 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
11b70 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
11b80 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
11b90 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
11ba0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
11bb0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11bc0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11bd0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11be0 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
11bf0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
11c00 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
11c10 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
11c20 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
11c30 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
11c40 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
11c50 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
11c60 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
11c70 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
11c80 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
11c90 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
11ca0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
11cb0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
11cc0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
11cd0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11ce0 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
11cf0 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
11d00 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
11d10 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
11d20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
11d30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
11d40 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
11d50 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
11d60 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
11d70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
11d80 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
11d90 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
11da0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
11db0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
11dc0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
11dd0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
11de0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11df0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
11e00 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
11e10 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
11e20 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
11e30 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
11e40 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
11e50 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
11e60 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
11e70 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
11e80 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
11e90 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
11ea0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
11eb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
11ec0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
11ed0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
11ee0 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
11ef0 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
11f00 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
11f10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f20 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
11f30 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
11f40 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
11f50 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
11f60 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
11f70 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
11f80 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
11f90 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
11fa0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
11fb0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
11fc0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
11fd0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
11fe0 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
11ff0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12000 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
12010 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
12020 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
12030 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
12040 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12050 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
12060 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
12070 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
12080 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12090 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
120a0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
120b0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
120c0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
120d0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
120e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
120f0 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
12100 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12110 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12120 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12130 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
12140 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12150 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
12160 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
12170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12180 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
12190 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
121a0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
121b0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
121c0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
121d0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
121e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
121f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12200 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
12210 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
12220 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
12230 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
12240 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
12250 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
12260 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12270 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12280 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12290 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
122a0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
122b0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
122c0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
122d0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
122e0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
122f0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
12300 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12310 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
12320 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
12330 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
12340 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
12350 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
12360 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12370 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
12380 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
12390 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
123a0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
123b0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
123c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
123d0 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
123e0 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
123f0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
12400 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
12410 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
12420 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
12430 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
12440 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
12450 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
12460 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
12470 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
12480 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
12490 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
124a0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
124b0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
124c0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
124d0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
124e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
124f0 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
12500 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
12510 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
12520 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
12530 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
12540 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
12550 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
12560 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
12570 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
12580 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12590 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
125a0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
125b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
125c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
125d0 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
125e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
125f0 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
12600 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
12610 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
12620 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
12630 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
12640 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
12650 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
12660 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
12670 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
12680 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12690 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
126a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
126b0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
126c0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
126d0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
126e0 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
126f0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
12700 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
12710 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
12720 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
12730 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
12740 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
12750 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
12760 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
12770 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
12780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
12790 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
127a0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
127b0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
127c0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
127d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
127e0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
127f0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
12800 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
12810 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
12820 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
12830 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
12840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12850 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
12860 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
12870 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12880 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
12890 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
128a0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
128b0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
128c0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
128d0 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
128e0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
128f0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
12900 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
12910 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
12920 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
12930 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
12940 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
12950 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
12960 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
12970 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
12980 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
12990 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
129a0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
129b0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
129c0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
129d0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
129e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
129f0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
12a00 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
12a10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12a20 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12a30 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12a40 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
12a50 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
12a60 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
12a70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12a80 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
12a90 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
12aa0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
12ab0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
12ac0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
12ad0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
12ae0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
12af0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12b00 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
12b10 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
12b20 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
12b30 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
12b40 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12b50 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
12b60 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
12b70 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
12b80 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
12b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
12ba0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
12bb0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
12bc0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
12bd0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
12be0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
12bf0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12c00 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
12c10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
12c20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
12c30 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
12c40 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
12c50 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
12c60 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
12c70 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
12c80 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
12c90 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
12ca0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
12cb0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
12cc0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
12cd0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
12ce0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
12cf0 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
12d00 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
12d10 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12d20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12d30 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12d40 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12d50 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
12d60 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
12d70 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
12d80 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
12d90 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12da0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
12db0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
12dc0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
12dd0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
12de0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
12df0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
12e00 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
12e10 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
12e20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
12e30 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
12e40 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
12e50 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
12e60 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
12e70 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
12e80 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
12e90 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
12ea0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
12eb0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
12ec0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
12ed0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
12ee0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
12ef0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
12f00 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
12f10 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
12f20 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
12f30 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
12f40 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
12f50 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
12f60 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
12f70 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
12f80 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
12f90 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
12fa0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
12fb0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
12fc0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
12fd0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
12fe0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
12ff0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13000 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
13010 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
13020 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
13030 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
13040 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
13050 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
13060 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
13070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
13080 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
13090 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
130a0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
130b0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
130c0 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
130d0 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
130e0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
130f0 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
13100 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
13110 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
13120 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
13130 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
13140 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
13150 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
13160 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
13170 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
13180 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
13190 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
131a0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
131b0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
131c0 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
131d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
131e0 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
131f0 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
13200 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
13210 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
13220 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
13230 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
13240 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
13250 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
13260 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13270 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
13280 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
13290 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
132a0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
132b0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
132c0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
132d0 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
132e0 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
132f0 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
13300 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
13310 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
13320 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
13330 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
13340 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
13350 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
13360 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13370 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
13380 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
13390 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
133a0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
133b0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
133c0 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
133d0 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
133e0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
133f0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
13400 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
13410 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
13420 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13430 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
13440 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
13450 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
13460 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
13470 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
13480 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
13490 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
134a0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
134b0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
134c0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
134d0 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
134e0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
134f0 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
13500 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
13510 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
13520 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
13530 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
13540 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
13550 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
13560 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
13570 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
13580 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
13590 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
135a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
135b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
135c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
135d0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
135e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
135f0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
13600 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
13610 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
13620 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
13630 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13640 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
13650 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
13660 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
13670 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
13680 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
13690 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
136a0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
136b0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
136c0 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
136d0 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
136e0 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
136f0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
13700 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
13710 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
13720 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
13730 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
13740 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
13750 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
13760 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
13770 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
13780 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
13790 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
137a0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
137b0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
137c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
137d0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
137e0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
137f0 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
13800 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
13810 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
13820 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
13830 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
13840 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
13850 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
13860 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
13870 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
13880 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
13890 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
138a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
138b0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
138c0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
138d0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
138e0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
138f0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
13900 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
13910 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
13920 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
13930 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
13940 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
13950 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
13960 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
13970 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
13980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13990 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
139a0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
139b0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
139c0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
139d0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
139e0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
139f0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
13a00 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
13a10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13a20 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
13a30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
13a40 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
13a50 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
13a60 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
13a70 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
13a80 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
13a90 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
13aa0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
13ab0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
13ac0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
13ad0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
13ae0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
13af0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
13b00 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
13b10 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
13b20 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
13b30 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
13b40 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
13b50 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
13b60 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
13b70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
13b80 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
13b90 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
13ba0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
13bb0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
13bc0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
13bd0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
13be0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
13bf0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
13c00 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
13c10 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
13c20 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
13c30 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
13c40 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
13c50 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
13c60 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
13c70 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
13c80 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
13c90 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
13ca0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
13cb0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
13cc0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
13cd0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
13ce0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
13cf0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
13d00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
13d10 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
13d20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
13d30 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
13d40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
13d50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
13d60 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
13d70 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
13d80 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
13d90 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
13da0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
13db0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
13dc0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
13dd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
13de0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
13df0 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
13e00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
13e10 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
13e20 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
13e30 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
13e40 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13e50 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13e60 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
13e70 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
13e80 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
13e90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
13ea0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
13eb0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
13ec0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
13ed0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
13ee0 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
13ef0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13f00 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
13f10 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
13f20 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
13f30 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
13f40 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
13f50 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
13f60 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
13f70 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
13f80 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
13f90 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
13fa0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
13fb0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
13fc0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
13fd0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13fe0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
13ff0 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
14000 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
14010 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
14020 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
14030 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14040 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
14050 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14060 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
14070 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14080 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
14090 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
140a0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
140b0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
140c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
140d0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
140e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
140f0 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
14100 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14110 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ote>.**.** ^The 
14120 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14130 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
14140 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
14150 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
14160 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
14170 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
14180 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
14190 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
141a0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
141b0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
141c0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
141d0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
141e0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
141f0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
14200 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
14210 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
14220 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
14230 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
14240 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
14250 0a 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61  .** it should pa
14260 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
14270 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
14280 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14290 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
142a0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
142b0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
142c0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
142d0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
142e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
142f0 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
14300 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
14310 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
14320 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
14330 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
14340 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
14350 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
14360 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
14370 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
14380 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
14390 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
143a0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
143b0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  fely..**.** ^(Th
143c0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
143d0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
143e0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
143f0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
14400 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
14410 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
14420 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14430 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
14440 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
14450 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
14460 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
14470 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
14480 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
14490 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
144a0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
144b0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
144c0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
144d0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
144e0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
144f0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
14500 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
14510 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
14520 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
14530 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
14540 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
14550 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
14560 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
14570 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  ()].)^.*/.int sq
14580 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14590 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
145a0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
145b0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
145c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
145d0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
145e0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
145f0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
14600 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
14610 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
14620 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
14630 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
14640 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
14650 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
14660 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
14670 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
14680 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
14690 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
146a0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
146b0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
146c0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
146d0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
146e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
146f0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
14700 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
14710 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
14720 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
14730 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
14740 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
14750 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
14760 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
14770 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
14780 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
14790 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
147a0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
147b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
147c0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
147d0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
147e0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
147f0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
14800 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
14810 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
14820 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
14830 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
14840 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
14850 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
14860 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
14870 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
14880 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
14890 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
148a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
148b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
148c0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
148d0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
148e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
148f0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
14900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
14910 28 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  (In sqlite3_snpr
14920 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
14930 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
14940 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
14950 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
14960 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
14970 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
14980 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
14990 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
149a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
149b0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
149c0 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
149d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
149e0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
149f0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
14a00 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
14a10 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
14a20 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
14a30 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
14a40 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
14a50 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
14a60 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
14a70 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
14a80 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
14a90 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
14aa0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
14ab0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14ac0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
14ad0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
14ae0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
14af0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
14b00 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
14b10 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
14b20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
14b30 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
14b40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
14b50 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
14b60 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
14b70 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
14b80 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
14b90 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
14ba0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
14bb0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
14bc0 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
14bd0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
14be0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
14bf0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
14c00 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
14c10 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
14c20 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
14c30 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
14c40 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
14c50 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
14c60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
14c70 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
14c80 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
14c90 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
14ca0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
14cb0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
14cc0 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
14cd0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
14ce0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
14cf0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
14d00 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
14d10 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
14d20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
14d30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
14d40 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
14d50 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
14d60 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
14d70 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
14d80 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
14d90 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
14da0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
14db0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
14dc0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
14dd0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
14de0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
14df0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
14e00 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
14e10 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
14e20 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
14e30 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
14e40 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
14e50 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
14e60 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
14e70 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
14e80 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
14e90 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
14ea0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
14eb0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
14ec0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
14ed0 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
14ee0 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
14ef0 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
14f00 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
14f10 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
14f20 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
14f30 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
14f40 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
14f50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
14f60 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
14f70 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
14f80 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
14f90 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
14fa0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14fb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14fc0 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
14fd0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
14fe0 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
14ff0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15000 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
15010 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
15020 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
15030 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
15040 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15050 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
15060 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15070 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
15080 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
15090 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
150a0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
150b0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
150c0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
150d0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
150e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
150f0 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
15100 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
15110 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
15120 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
15130 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
15140 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
15150 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
15160 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
15170 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
15180 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
15190 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
151a0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
151b0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
151c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
151d0 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
151e0 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
151f0 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
15200 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
15210 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
15220 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
15230 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
15240 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15250 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15260 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
15270 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
15280 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15290 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
152a0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
152b0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
152c0 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
152d0 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
152e0 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
152f0 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
15300 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
15310 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
15320 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
15330 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
15340 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
15350 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
15360 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
15370 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
15380 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
15390 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
153a0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
153b0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
153c0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
153d0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
153e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
153f0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
15400 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
15410 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
15420 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
15430 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
15440 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
15450 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15460 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
15470 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
15480 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
15490 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
154a0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
154b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
154c0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
154d0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
154e0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
154f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15500 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
15510 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
15520 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
15530 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
15540 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
15550 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
15560 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
15570 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
15580 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
15590 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
155a0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
155b0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
155c0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
155d0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
155e0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
155f0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
15600 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
15610 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
15620 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
15630 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
15640 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
15650 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
15660 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
15670 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
15680 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
15690 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
156a0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
156b0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
156c0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
156d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
156e0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
156f0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
15700 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
15710 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
15720 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
15730 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
15740 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
15750 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15760 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
15770 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
15780 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
15790 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
157a0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
157b0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
157c0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
157d0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
157e0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
157f0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
15800 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
15810 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
15820 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
15830 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
15840 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
15850 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
15860 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
15870 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
15880 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
15890 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
158a0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
158b0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
158c0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
158d0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
158e0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
158f0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
15900 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
15910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
15920 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
15930 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
15940 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
15950 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
15960 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
15970 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
15980 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
15990 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
159a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
159b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
159c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
159d0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
159e0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
159f0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
15a00 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
15a10 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
15a20 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
15a30 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
15a40 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
15a50 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
15a60 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
15a70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
15a80 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
15a90 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
15aa0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
15ab0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
15ac0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
15ad0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
15ae0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
15af0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
15b00 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
15b10 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
15b20 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
15b30 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
15b40 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
15b50 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
15b60 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
15b70 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
15b80 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
15b90 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
15ba0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
15bb0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
15bc0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
15bd0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
15be0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
15bf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15c00 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
15c10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
15c20 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
15c30 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
15c40 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
15c50 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
15c60 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
15c70 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
15c80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15c90 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
15ca0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
15cb0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
15cc0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
15cd0 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
15ce0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15cf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15d00 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
15d10 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
15d20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
15d30 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
15d40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
15d50 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
15d60 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15d70 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
15d80 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
15d90 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
15da0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
15dc0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
15dd0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
15de0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
15df0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
15e00 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
15e10 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
15e20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
15e30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15e40 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
15e50 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
15e60 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
15e70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
15e80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
15e90 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
15ea0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
15eb0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
15ec0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
15ed0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
15ee0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
15ef0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15f00 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
15f10 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
15f20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15f30 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
15f40 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
15f50 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
15f60 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
15f70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
15f80 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
15f90 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
15fa0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
15fb0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
15fc0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
15fd0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15fe0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
15ff0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
16000 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
16010 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
16020 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
16030 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
16040 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
16050 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
16060 74 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a  te boundary..**.
16070 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
16080 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
16090 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
160a0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
160b0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
160c0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
160d0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
160e0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
160f0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
16100 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
16110 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
16120 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
16130 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
16140 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
16150 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
16160 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16170 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
16180 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
16190 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
161a0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
161b0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
161c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
161d0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
161e0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
161f0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
16200 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
16210 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
16220 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
16230 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
16240 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
16250 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
16260 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
16270 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
16280 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
16290 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
162a0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
162b0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
162c0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
162d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
162e0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
162f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
16300 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
16310 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
16320 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
16330 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
16340 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
16350 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
16360 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
16370 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
16380 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
16390 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
163a0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
163b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
163c0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
163d0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
163e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
163f0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
16400 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
16410 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
16420 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
16430 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
16440 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
16450 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
16460 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
16470 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
16480 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
16490 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
164a0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
164b0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
164c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
164d0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
164e0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
164f0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
16500 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
16510 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
16520 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
16530 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
16540 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
16550 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16560 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
16570 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
16580 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16590 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
165a0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
165b0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
165c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
165d0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
165e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
165f0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
16600 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
16610 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
16620 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
16630 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
16640 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
16650 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
16660 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
16670 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
16680 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
16690 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
166a0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
166b0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
166c0 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
166d0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
166e0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
166f0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
16700 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
16710 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
16720 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
16730 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
16740 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
16750 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
16760 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
16770 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16780 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
16790 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
167a0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
167b0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
167c0 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
167d0 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
167e0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
167f0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
16800 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
16810 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
16820 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
16830 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
16840 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
16850 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16860 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
16870 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
16880 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
16890 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
168a0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
168b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
168c0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
168d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
168e0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
168f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
16900 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
16910 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
16920 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
16930 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
16940 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16950 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
16960 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
16970 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
16980 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
16990 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
169a0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
169b0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
169c0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
169d0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
169e0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
169f0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
16a00 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
16a10 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
16a20 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
16a30 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
16a40 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
16a50 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
16a60 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
16a70 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
16a80 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
16a90 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
16aa0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
16ab0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
16ac0 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
16ad0 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
16ae0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
16af0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
16b00 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
16b10 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
16b20 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
16b30 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
16b40 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
16b50 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
16b60 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
16b70 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
16b80 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
16b90 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
16ba0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
16bb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
16bc0 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
16bd0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
16be0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
16bf0 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
16c00 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
16c10 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
16c20 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
16c30 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
16c40 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
16c50 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
16c60 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
16c70 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
16c80 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
16c90 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
16ca0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
16cb0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
16cc0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
16cd0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
16ce0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
16cf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d00 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
16d10 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
16d20 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
16d30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
16d40 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69  isters a authori
16d50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
16d60 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
16d70 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
16d80 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
16d90 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
16da0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
16db0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16dc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
16dd0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
16de0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
16df0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
16e00 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
16e10 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
16e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16e30 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16e40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
16e50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
16e60 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
16e70 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
16e80 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
16e90 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
16ea0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
16eb0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
16ec0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
16ed0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
16ee0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16ef0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16f00 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
16f10 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
16f20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
16f30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16f40 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
16f50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
16f60 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
16f70 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
16f80 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
16f90 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
16fa0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
16fb0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
16fc0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
16fd0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
16fe0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
16ff0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
17000 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
17010 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
17020 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
17030 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
17040 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17050 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
17060 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
17070 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
17080 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
17090 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
170a0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
170b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
170c0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
170d0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
170e0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
170f0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
17100 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
17110 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
17120 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
17130 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
17140 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
17150 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
17160 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
17170 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
17180 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17190 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
171a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
171b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
171c0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
171d0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
171e0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
171f0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
17200 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
17210 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
17220 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
17230 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
17240 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
17250 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
17260 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17270 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
17280 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
17290 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
172a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
172b0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
172c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
172d0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
172e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
172f0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
17300 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
17310 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
17320 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
17330 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
17340 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
17350 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
17360 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
17370 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
17380 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
17390 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
173a0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
173b0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
173c0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
173d0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
173e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
173f0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
17400 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
17410 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
17420 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17430 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
17440 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
17450 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
17460 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
17470 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
17480 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
17490 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
174a0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
174b0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
174c0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
174d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
174e0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
174f0 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
17500 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
17510 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
17520 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
17530 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
17540 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
17550 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
17560 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
17570 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
17580 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
17590 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
175a0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
175b0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
175c0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
175d0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
175e0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
175f0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
17600 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
17610 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
17620 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
17630 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
17640 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
17650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17660 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
17670 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
17680 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
17690 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
176a0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
176b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
176c0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
176d0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
176e0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
176f0 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
17700 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
17710 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
17720 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
17730 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
17740 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
17750 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
17760 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
17770 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
17780 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
17790 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
177a0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
177b0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
177c0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
177d0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
177e0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
177f0 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
17800 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
17810 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
17820 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
17830 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
17840 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
17850 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
17860 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
17870 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
17880 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
17890 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
178a0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
178b0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
178c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
178d0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
178e0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
178f0 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
17900 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
17910 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
17920 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
17930 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
17940 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
17950 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
17960 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
17970 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
17980 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
17990 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
179a0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
179b0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
179c0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
179d0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
179e0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
179f0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
17a00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
17a10 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
17a20 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
17a30 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
17a40 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
17a50 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
17a60 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
17a70 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
17a80 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
17a90 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
17aa0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
17ab0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
17ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
17ad0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
17ae0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
17af0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
17b00 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
17b10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17b20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
17b30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17b40 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
17b50 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
17b60 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
17b70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
17b80 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
17b90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17ba0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
17bb0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
17bc0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
17bd0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
17be0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
17bf0 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
17c00 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
17c10 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
17c20 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
17c30 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
17c40 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
17c50 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
17c60 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
17c70 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
17c80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
17c90 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
17ca0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
17cb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17cc0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
17cd0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
17ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17cf0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
17d00 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
17d10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17d20 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
17d30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17d40 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
17d50 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
17d60 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
17d70 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
17d80 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
17d90 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
17da0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
17db0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
17dc0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
17dd0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
17de0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
17df0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
17e00 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
17e10 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17e20 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
17e30 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
17e40 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
17e50 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
17e60 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
17e70 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
17e80 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
17e90 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
17ea0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
17eb0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
17ec0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
17ed0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17ee0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
17ef0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17f00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17f10 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
17f20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
17f30 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
17f40 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
17f50 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
17f60 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
17f70 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
17f80 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
17f90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
17fa0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
17fb0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
17fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
17fd0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17fe0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
17ff0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
18000 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
18010 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
18020 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
18030 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
18040 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
18050 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
18060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
18070 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
18080 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
18090 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
180a0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
180b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
180c0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
180d0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
180e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
180f0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
18100 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
18110 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18120 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
18130 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
18140 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
18150 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
18160 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
18170 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
18180 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
18190 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
181a0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
181b0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
181c0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
181d0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
181e0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
181f0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
18200 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18210 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
18220 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
18230 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
18240 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
18250 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
18260 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
18270 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
18280 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
18290 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
182a0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
182b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
182c0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
182d0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
182e0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
182f0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
18300 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
18310 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18320 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
18330 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
18340 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18350 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
18360 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18370 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
18380 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
18390 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
183a0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
183b0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
183c0 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
183d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
183e0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
183f0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
18400 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
18410 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
18420 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
18430 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
18440 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
18450 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
18460 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
18470 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
18480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
184a0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
184b0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
184c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
184d0 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
184e0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
184f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
18500 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18520 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
18530 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
18540 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18550 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18570 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
18580 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
18590 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
185a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
185b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
185c0 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
185d0 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
185e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
185f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18610 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
18620 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
18630 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
18640 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18660 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
18670 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
18680 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
18690 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
186a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
186b0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
186c0 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
186d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
186e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
186f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18700 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
18710 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
18720 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
18730 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18740 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
18750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18760 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
18770 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18780 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18790 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
187a0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
187b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
187c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
187d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
187e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
187f0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
18800 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18810 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18830 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
18840 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
18850 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18860 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18870 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18880 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18890 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
188a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
188b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
188c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
188d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
188e0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
188f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18900 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18910 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18920 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
18930 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
18940 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18950 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18960 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18970 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
18980 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
18990 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
189a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
189b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
189c0 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
189d0 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
189e0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
189f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a10 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
18a20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
18a30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18a40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a60 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
18a70 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
18a80 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
18a90 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
18aa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
18ab0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
18ac0 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
18ad0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
18ae0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
18af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
18b00 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
18b10 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
18b20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
18b30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
18b50 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
18b60 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
18b70 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
18b80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18b90 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
18ba0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
18bb0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
18bc0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
18bd0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18be0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
18bf0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18c00 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
18c10 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18c20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18c30 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
18c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18c50 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
18c60 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
18c70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18c80 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
18c90 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
18ca0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
18cb0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
18cc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18cd0 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
18ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
18cf0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18d00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18d10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18d20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
18d30 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
18d40 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18d50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18d60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18d70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
18d80 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
18d90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18da0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
18db0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18dc0 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
18dd0 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
18de0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18df0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
18e00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18e10 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
18e20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
18e30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18e40 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
18e50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18e60 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
18e70 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
18e80 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
18e90 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
18ea0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18eb0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
18ec0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
18ed0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
18ee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18ef0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
18f00 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
18f10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
18f20 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
18f30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18f40 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
18f50 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
18f60 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
18f70 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
18f80 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
18f90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
18fa0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18fb0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18fc0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
18fd0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
18fe0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
18ff0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
19000 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
19010 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
19020 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
19030 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
19040 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
19050 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
19060 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
19070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
19080 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
19090 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
190a0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
190b0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
190c0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
190d0 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
190e0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
190f0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
19100 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
19110 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
19120 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
19130 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
19140 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
19150 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
19160 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
19170 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19180 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
19190 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
191a0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
191b0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
191c0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
191d0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
191e0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
191f0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
19200 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
19210 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
19220 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
19230 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
19240 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
19250 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
19260 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
19270 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
19280 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
19290 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
192a0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
192b0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
192c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
192d0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
192e0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
192f0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
19300 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
19310 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
19320 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
19330 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
19340 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
19350 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
19360 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
19370 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
19380 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
19390 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
193a0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
193b0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
193c0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
193d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
193e0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
193f0 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
19400 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
19410 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
19420 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
19430 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
19440 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
19450 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
19460 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
19470 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73   ^If the progres
19480 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
19490 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
194a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
194b0 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
194c0 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
194d0 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
194e0 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
194f0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
19500 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
19510 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
19520 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
19530 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  er must not do a
19540 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
19550 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
19560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19570 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
19580 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
19590 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
195a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
195b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
195c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
195d0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
195e0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
195f0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
19600 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
19610 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
19620 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
19630 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
19640 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
19650 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
19660 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
19670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19680 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
19690 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
196a0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
196b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
196c0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
196d0 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e  ase file whose n
196e0 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ame is given by 
196f0 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
19700 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
19710 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
19720 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
19730 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
19740 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
19750 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
19760 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
19770 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
19780 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
19790 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
197a0 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
197b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
197c0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
197d0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
197e0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
197f0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
19800 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
19810 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
19820 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
19830 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
19840 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
19850 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
19860 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
19870 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
19880 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
19890 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
198a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
198b0 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
198c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
198d0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
198e0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
198f0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
19900 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
19910 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
19920 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
19930 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
19940 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
19950 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
19960 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
19970 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
19980 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
19990 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
199a0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
199b0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
199c0 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
199d0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
199e0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
199f0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
19a00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
19a10 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
19a20 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
19a30 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
19a40 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19a50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
19a60 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
19a70 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
19a80 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19a90 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
19aa0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
19ab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
19ac0 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
19ad0 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
19ae0 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
19af0 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
19b00 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
19b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19b20 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
19b30 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
19b40 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
19b50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
19b60 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
19b70 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
19b80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
19b90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19ba0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
19bb0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
19bc0 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
19bd0 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
19be0 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
19bf0 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
19c00 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
19c10 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
19c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19c30 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
19c40 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
19c50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19c60 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
19c70 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
19c80 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
19c90 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
19ca0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
19cb0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
19cc0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
19cd0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19ce0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
19cf0 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
19d00 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
19d10 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
19d20 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
19d30 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
19d40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
19d50 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
19d60 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
19d70 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
19d80 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
19d90 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
19da0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
19db0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
19dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
19dd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
19de0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
19df0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
19e00 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
19e10 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
19e20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
19e30 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
19e40 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
19e50 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
19e60 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
19e70 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
19e80 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
19e90 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
19ea0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
19eb0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
19ec0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
19ed0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
19ee0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
19ef0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19f00 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
19f10 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
19f20 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
19f30 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
19f40 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
19f50 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
19f60 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20  d is creates it 
19f70 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
19f80 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
19f90 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
19fa0 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
19fb0 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
19fc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19fd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
19fe0 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
19ff0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1a000 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1a010 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1a020 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1a030 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1a040 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1a050 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ove or one of th
1a060 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  e combinations s
1a070 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69  hown above combi
1a080 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ned.** with the 
1a090 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a0a0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1a0b0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a  PEN_FULLMUTEX],.
1a0c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1a0d0 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64  SHAREDCACHE] and
1a0e0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1a0f0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1a100 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1a110 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1a120 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1a130 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1a140 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1a150 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1a160 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a170 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1a180 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1a190 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1a1a0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1a1b0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1a1c0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1a1d0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1a1e0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1a1f0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1a200 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1a210 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1a220 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1a230 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a240 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1a250 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1a260 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1a270 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1a280 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1a290 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1a2a0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1a2b0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1a2c0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1a2d0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1a2e0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1a2f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a300 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1a310 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1a320 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1a330 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1a340 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1a350 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1a360 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1a370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1a380 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1a390 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1a3a0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1a3b0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1a3c0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1a3d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1a3e0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1a3f0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1a400 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1a410 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1a420 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1a430 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1a440 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1a450 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1a460 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1a470 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1a480 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1a490 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1a4a0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1a4b0 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1a4c0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1a4d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1a4e0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1a4f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1a500 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1a510 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1a520 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1a530 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1a540 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1a550 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1a560 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1a570 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1a580 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1a590 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1a5a0 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1a5b0 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1a5c0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1a5d0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1a5e0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1a5f0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1a600 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1a610 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1a620 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1a630 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1a640 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1a650 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1a660 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1a670 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1a680 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1a690 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1a6a0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1a6b0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1a6c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1a6d0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   closed..**.** ^
1a6e0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1a6f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1a700 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1a710 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1a720 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1a730 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1a740 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1a750 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1a760 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1a770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a780 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1a790 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1a7a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1a7b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1a7c0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1a7d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1a7e0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1a7f0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1a800 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1a810 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1a820 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1a830 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1a840 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1a850 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1a860 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1a870 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1a880 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1a890 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1a8a0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1a8b0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1a8c0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1a8d0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1a8e0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1a8f0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1a900 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1a910 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1a920 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1a930 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20  en_v2()..*/.int 
1a940 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1a950 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1a960 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1a970 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1a980 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1a990 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1a9a0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1a9b0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1a9c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1a9d0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1a9e0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1a9f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1aa00 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1aa10 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1aa20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1aa30 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1aa40 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1aa50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1aa60 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1aa70 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1aa80 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1aa90 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1aaa0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1aab0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1aac0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1aad0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1aae0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1aaf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ab00 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1ab10 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1ab20 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1ab30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab40 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1ab50 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
1ab60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1ab70 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
1ab80 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1ab90 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
1aba0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
1abb0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1abc0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1abd0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
1abe0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
1abf0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1ac00 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1ac10 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
1ac20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
1ac30 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
1ac40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
1ac50 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
1ac60 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1ac70 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
1ac80 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
1ac90 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
1aca0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1acb0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
1acc0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
1acd0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
1ace0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
1acf0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
1ad00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1ad10 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
1ad20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1ad30 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
1ad40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ad50 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1ad60 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1ad70 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1ad80 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1ad90 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1ada0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1adb0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1adc0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1add0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
1ade0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1adf0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1ae00 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1ae10 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1ae20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1ae30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1ae40 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1ae50 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1ae60 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1ae70 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1ae80 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1ae90 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1aea0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1aeb0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1aec0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1aed0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
1aee0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
1aef0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1af00 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
1af10 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
1af20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
1af30 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
1af40 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
1af50 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
1af60 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
1af70 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
1af80 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
1af90 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
1afa0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
1afb0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
1afc0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
1afd0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
1afe0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
1aff0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
1b000 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
1b010 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
1b020 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
1b030 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
1b040 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
1b050 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
1b060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b070 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
1b080 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1b090 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
1b0a0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1b0b0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
1b0c0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
1b0d0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
1b0e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
1b0f0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
1b100 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
1b110 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
1b120 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
1b130 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
1b140 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
1b150 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
1b160 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
1b170 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
1b180 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
1b190 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
1b1a0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
1b1b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b1c0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
1b1d0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
1b1e0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
1b1f0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
1b200 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
1b210 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1b220 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1b230 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1b240 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1b250 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1b260 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1b270 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1b280 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1b290 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1b2a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b2b0 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1b2c0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
1b2d0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1b2e0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1b2f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1b300 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1b310 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1b320 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1b330 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1b340 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1b350 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1b360 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1b370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b380 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1b390 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1b3a0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1b3b0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1b3c0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1b3d0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1b3e0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1b3f0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1b400 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1b410 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1b420 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1b430 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b440 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1b450 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1b460 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1b470 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1b480 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1b490 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b4a0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1b4b0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1b4c0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1b4d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1b4e0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1b4f0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1b500 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1b510 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1b520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1b530 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1b540 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1b550 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1b560 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1b570 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1b580 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1b590 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1b5a0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1b5b0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1b5c0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1b5d0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1b5e0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1b5f0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1b600 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1b610 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1b620 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1b630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b640 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1b650 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
1b660 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1b670 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1b680 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1b690 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1b6a0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1b6b0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1b6c0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1b6d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1b6e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1b6f0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1b700 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1b710 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1b720 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1b730 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1b740 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1b750 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1b760 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1b770 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1b780 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1b790 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1b7a0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1b7b0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1b7c0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1b7d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1b7e0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1b7f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1b800 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1b810 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1b820 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1b830 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1b840 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1b850 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1b860 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1b870 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1b880 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1b890 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
1b8a0 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
1b8b0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1b8c0 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
1b8d0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
1b8e0 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
1b8f0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1b900 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1b910 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
1b920 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
1b930 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
1b940 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
1b950 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
1b960 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
1b970 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
1b980 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
1b990 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1b9a0 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1b9b0 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1b9c0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1b9d0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1b9e0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1b9f0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1ba00 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1ba10 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1ba20 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1ba30 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1ba40 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1ba50 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1ba60 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1ba70 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1ba80 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1ba90 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1baa0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1bab0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1bac0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1bad0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1bae0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1baf0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1bb00 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1bb10 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1bb20 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1bb30 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1bb40 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1bb50 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1bb60 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1bb70 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1bb80 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1bb90 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1bba0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1bbb0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1bbc0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1bbd0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1bbe0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1bbf0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bc00 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1bc10 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1bc20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1bc30 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1bc40 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1bc50 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1bc60 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1bc70 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1bc80 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1bc90 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1bca0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1bcb0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1bcc0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1bcd0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1bce0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1bcf0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1bd00 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1bd10 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1bd20 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1bd30 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1bd40 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
1bd50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1bd60 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
1bd70 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1bd80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1bd90 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1bda0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
1bdb0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
1bdc0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
1bdd0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
1bde0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1bdf0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
1be00 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
1be10 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
1be20 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
1be30 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
1be40 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1be50 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
1be60 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
1be70 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
1be80 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
1be90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1bea0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1beb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1bec0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1bed0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1bee0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29   table row.<dd>)
1bef0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1bf00 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1bf10 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1bf20 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1bf30 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1bf40 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
1bf50 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
1bf60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1bf70 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1bf80 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1bf90 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1bfa0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1bfb0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1bfc0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1bfd0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1bfe0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1bff0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1c000 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1c010 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1c020 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1c030 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
1c040 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c050 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1c060 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1c070 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1c080 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1c090 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1c0a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
1c0b0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c0c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1c0d0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
1c0e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c0f0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
1c100 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
1c110 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
1c120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c130 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1c140 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
1c150 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c160 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
1c170 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
1c180 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
1c190 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
1c1a0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
1c1b0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
1c1c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c1d0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1c1e0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1c1f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c200 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1c210 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1c220 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c230 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c240 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1c250 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c260 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1c270 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1c280 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
1c290 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c2a0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1c2b0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1c2c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c2d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1c2e0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1c2f0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
1c300 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
1c310 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
1c320 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c330 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1c340 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1c350 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c360 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1c370 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1c380 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1c390 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1c3a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c3b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c3c0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
1c3d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c3e0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1c3f0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
1c400 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
1c410 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1c420 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c430 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1c440 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1c450 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c460 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1c470 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1c480 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c490 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1c4a0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1c4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c4c0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1c4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1c4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c4f0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1c500 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1c510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c520 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1c530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1c540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c550 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1c560 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1c570 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1c580 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1c590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c5a0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1c5b0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1c5c0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1c5d0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1c5e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1c5f0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1c600 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
1c610 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1c620 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1c630 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
1c640 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1c650 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1c660 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1c670 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1c680 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
1c690 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
1c6a0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
1c6b0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
1c6c0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
1c6d0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
1c6e0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
1c6f0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1c700 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1c710 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
1c720 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c730 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
1c740 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
1c750 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1c760 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1c770 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1c780 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
1c790 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1c7a0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
1c7b0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
1c7c0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
1c7d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
1c7e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1c7f0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1c800 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1c810 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1c820 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1c830 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1c840 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1c850 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1c860 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1c870 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1c880 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1c890 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1c8a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c8b0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1c8c0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1c8d0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
1c8e0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1c8f0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1c900 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1c910 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1c920 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1c930 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
1c940 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1c950 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1c960 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1c970 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1c980 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
1c990 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1c9a0 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1c9b0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1c9c0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1c9d0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1c9e0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1c9f0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1ca00 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1ca10 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1ca20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1ca30 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1ca40 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1ca50 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1ca60 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1ca70 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1ca80 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1ca90 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1caa0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1cab0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1cac0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1cad0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1cae0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1caf0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1cb00 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1cb10 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1cb20 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
1cb30 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1cb40 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1cb50 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1cb60 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1cb70 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1cb80 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1cb90 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1cba0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1cbb0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1cbc0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1cbd0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1cbe0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1cbf0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1cc00 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1cc10 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1cc20 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
1cc30 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1cc40 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1cc50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1cc60 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1cc70 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1cc80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1cc90 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
1cca0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1ccb0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1ccc0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
1ccd0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1cce0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1ccf0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1cd00 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1cd10 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1cd20 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1cd30 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
1cd40 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1cd50 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1cd60 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1cd70 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1cd80 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1cd90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1cda0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1cdb0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1cdc0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
1cdd0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
1cde0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
1cdf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
1ce00 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
1ce10 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ce20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
1ce30 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
1ce40 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1ce50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1ce60 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1ce70 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
1ce80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1ce90 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
1cea0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
1ceb0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
1cec0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
1ced0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
1cee0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
1cef0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1cf00 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
1cf10 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
1cf20 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
1cf30 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1cf40 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1cf50 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1cf60 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1cf70 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1cf80 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1cf90 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1cfa0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1cfb0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1cfc0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1cfd0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1cfe0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1cff0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
1d000 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
1d010 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1d020 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
1d030 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1d040 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1d050 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1d060 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1d070 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1d080 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1d090 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1d0a0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1d0b0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1d0c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1d0d0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1d0e0 20 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61    ^If the schema
1d0f0 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a   has changed in.
1d100 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61  ** a way that ma
1d110 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e  kes the statemen
1d120 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69  t no longer vali
1d130 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  d, [sqlite3_step
1d140 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a  ()] will still.*
1d150 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1d160 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75  _SCHEMA].  But u
1d170 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79  nlike the legacy
1d180 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49   behavior, [SQLI
1d190 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a  TE_SCHEMA] is.**
1d1a0 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72   now a fatal err
1d1b0 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71  or.  Calling [sq
1d1c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d1d0 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
1d1e0 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
1d1f0 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e  rror go away.  N
1d200 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65  ote: use [sqlite
1d210 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66  3_errmsg()] to f
1d220 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20  ind the text.** 
1d230 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65  of the parsing e
1d240 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74  rror that result
1d250 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  s in an [SQLITE_
1d260 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a  SCHEMA] return..
1d270 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1d280 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
1d290 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1d2a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d2b0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1d2c0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1d2d0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1d2e0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1d2f0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
1d300 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1d310 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1d320 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1d330 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1d340 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1d350 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1d360 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
1d370 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
1d380 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1d390 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1d3a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1d3b0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
1d3c0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1d3d0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1d3e0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1d3f0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1d400 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1d410 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1d420 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1d430 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1d440 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1d450 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1d460 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1d470 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65  e of a [paramete
1d480 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1d490 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45  er] in the WHERE
1d4a0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a   clause might.**
1d4b0 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72   change the quer
1d4c0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
1d4d0 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  tement, then the
1d4e0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62   statement may b
1d4f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1d500 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61  ly recompiled (a
1d510 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1d520 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61  een a schema cha
1d530 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73  nge) on the firs
1d540 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  t .** [sqlite3_s
1d550 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1d560 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1d570 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
1d580 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1d590 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1d5a0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  e [parameter]. .
1d5b0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1d5c0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1d5d0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1d5e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d5f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1d600 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d610 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d620 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1d630 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1d640 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d650 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d660 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d670 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d680 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d690 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d6a0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d6b0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d6c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1d6d0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d6e0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d6f0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d700 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1d710 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1d720 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1d740 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1d750 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1d760 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1d770 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1d780 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1d790 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1d7a0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1d7b0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1d7c0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1d7d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1d7e0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1d7f0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1d800 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1d810 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1d820 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1d830 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1d840 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1d850 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1d860 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1d870 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1d880 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1d890 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d8a0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1d8b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1d8c0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1d8d0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1d8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1d8f0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1d900 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1d910 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1d920 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1d930 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1d940 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d950 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1d960 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1d970 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1d980 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1d990 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1d9a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1d9b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1d9c0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1d9d0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1d9e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1d9f0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1da00 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1da10 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1da20 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1da30 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1da40 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1da50 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1da60 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1da70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1da80 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1da90 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1daa0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1dab0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1dac0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1dad0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1dae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1daf0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1db00 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1db10 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1db20 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1db30 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1db40 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1db50 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1db60 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1db70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1db80 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1db90 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1dba0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1dbb0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1dbc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1dbd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1dbe0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1dbf0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1dc00 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1dc10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1dc20 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1dc30 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1dc40 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1dc50 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1dc60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1dc70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1dc80 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1dc90 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1dca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dcb0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1dcc0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1dcd0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1dce0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1dcf0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1dd00 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1dd10 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1dd20 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1dd30 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
1dd40 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1dd50 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1dd60 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1dd70 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1dd80 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1dd90 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1dda0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1ddb0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1ddc0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1ddd0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1dde0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1ddf0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1de00 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1de10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1de20 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1de30 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1de40 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1de50 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1de60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1de70 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1de80 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1de90 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1dea0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1deb0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1dec0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1ded0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1dee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1def0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1df00 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1df10 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1df20 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1df30 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1df40 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1df50 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1df60 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1df70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1df80 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1df90 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1dfa0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1dfb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1dfc0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1dfd0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1dfe0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1dff0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1e000 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e010 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1e020 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1e030 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1e040 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1e050 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1e060 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1e070 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1e080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1e090 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1e0a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1e0b0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1e0c0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1e0d0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1e0e0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1e0f0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1e100 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e110 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1e120 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1e130 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1e140 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1e150 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1e160 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1e170 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1e180 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1e190 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1e1a0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65  ction between be
1e1b0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1e1c0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1e1d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1e1e0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1e1f0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1e200 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1e210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
1e220 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1e230 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1e240 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1e250 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1e260 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1e270 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1e280 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1e290 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
1e2a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e2b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1e2c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
1e2d0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
1e2e0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
1e2f0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
1e300 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e310 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
1e320 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
1e330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1e340 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
1e350 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
1e360 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1e370 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
1e380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
1e390 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
1e3a0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
1e3b0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
1e3c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e3d0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
1e3e0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
1e3f0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
1e400 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1e410 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1e420 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
1e430 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1e440 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1e450 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1e460 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1e470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1e480 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
1e490 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1e4a0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1e4b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
1e4c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1e4d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1e4e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1e4f0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1e500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1e510 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
1e520 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
1e530 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
1e540 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
1e550 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
1e560 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
1e570 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
1e580 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1e590 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1e5a0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
1e5b0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
1e5c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1e5d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
1e5e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
1e5f0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
1e600 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
1e610 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
1e620 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1e630 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
1e640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
1e650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e660 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1e670 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1e680 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
1e690 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
1e6a0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
1e6b0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
1e6c0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
1e6d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
1e6e0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
1e6f0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
1e700 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
1e710 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
1e720 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1e730 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1e740 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e750 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1e760 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1e770 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1e780 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
1e790 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
1e7a0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
1e7b0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
1e7c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
1e7d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
1e7e0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
1e7f0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
1e800 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
1e810 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
1e820 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
1e830 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
1e840 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1e850 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
1e860 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
1e870 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
1e880 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
1e890 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
1e8a0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
1e8b0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
1e8c0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
1e8d0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
1e8e0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
1e8f0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1e900 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1e910 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
1e920 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
1e930 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1e940 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1e950 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1e960 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1e970 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1e980 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1e990 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1e9a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e9b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1e9c0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1e9d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1e9e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
1e9f0 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
1ea00 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1ea10 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
1ea20 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
1ea30 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1ea40 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
1ea50 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
1ea60 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
1ea70 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
1ea80 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
1ea90 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
1eaa0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
1eab0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
1eac0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1ead0 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
1eae0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
1eaf0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
1eb00 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
1eb10 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1eb20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1eb30 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
1eb40 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
1eb50 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
1eb60 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
1eb70 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
1eb80 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
1eb90 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1eba0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
1ebb0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1ebc0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
1ebd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ebe0 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
1ebf0 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
1ec10 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1ec20 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1ec30 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1ec40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
1ec50 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1ec60 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1ec70 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1ec80 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1ec90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1eca0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1ecb0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1ecc0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1ecd0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1ece0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1ecf0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1ed00 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1ed10 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
1ed20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ed30 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1ed40 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1ed50 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
1ed60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1ed70 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
1ed80 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1ed90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  or..**.** ^The f
1eda0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1edb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1edc0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1edd0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1ede0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1edf0 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1ee00 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1ee10 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1ee20 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1ee30 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1ee40 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1ee50 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69 66 74  it. ^If the fift
1ee60 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
1ee70 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
1ee80 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
1ee90 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
1eea0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1eeb0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
1eec0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
1eed0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
1eee0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
1eef0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
1ef00 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
1ef10 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
1ef20 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
1ef30 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
1ef40 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
1ef50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
1ef60 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
1ef70 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
1ef80 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
1ef90 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1efa0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
1efb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1efc0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1efd0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1efe0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1eff0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1f000 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1f010 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
1f020 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
1f030 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
1f040 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
1f050 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
1f060 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
1f070 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
1f080 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
1f090 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
1f0a0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
1f0b0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
1f0c0 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
1f0d0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
1f0e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
1f0f0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
1f100 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
1f110 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
1f120 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
1f130 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
1f140 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
1f150 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
1f160 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
1f170 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f180 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
1f190 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
1f1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1f1b0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
1f1c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1f1d0 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
1f1e0 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
1f1f0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
1f200 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
1f210 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
1f220 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
1f230 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
1f240 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
1f250 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1f260 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
1f270 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
1f280 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
1f290 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
1f2a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f2b0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
1f2c0 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
1f2d0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
1f2e0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
1f2f0 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1f300 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
1f310 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1f320 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1f330 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
1f340 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1f350 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1f360 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1f370 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1f380 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
1f390 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1f3a0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
1f3b0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
1f3c0 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
1f3d0 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
1f3e0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
1f3f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1f400 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
1f410 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
1f420 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
1f430 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1f440 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
1f450 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
1f460 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1f470 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1f480 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1f490 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f4a0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
1f4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f4c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1f4d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f4e0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1f4f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1f500 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1f510 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f530 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1f540 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1f550 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1f560 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1f570 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f580 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1f590 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1f5a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f5b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1f5c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f5d0 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1f5e0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1f5f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1f600 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1f610 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1f620 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1f630 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1f640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1f650 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1f660 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1f670 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1f680 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1f690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1f6a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1f6b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1f6c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1f6d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1f6e0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1f6f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1f700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f710 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1f720 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
1f730 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1f740 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f750 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1f760 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1f770 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1f780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f790 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1f7a0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1f7b0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1f7c0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1f7d0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1f7e0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1f7f0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1f800 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1f810 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1f820 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1f830 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1f840 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1f850 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
1f860 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1f870 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1f880 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1f890 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
1f8a0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
1f8b0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
1f8c0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
1f8d0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
1f8e0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
1f8f0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
1f900 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
1f910 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
1f920 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
1f930 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1f940 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1f950 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
1f960 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1f970 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f980 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1f990 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f9a0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1f9b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f9c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1f9d0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
1f9e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f9f0 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
1fa00 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1fa10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
1fa20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
1fa30 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
1fa40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fa50 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
1fa60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1fa70 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
1fa80 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
1fa90 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
1faa0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fab0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
1fac0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
1fad0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
1fae0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1faf0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1fb00 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
1fb10 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
1fb20 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1fb30 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1fb40 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
1fb50 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
1fb60 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
1fb70 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
1fb80 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
1fb90 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
1fba0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
1fbb0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
1fbc0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1fbd0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
1fbe0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
1fbf0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
1fc00 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
1fc10 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
1fc20 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
1fc30 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
1fc40 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
1fc50 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
1fc60 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
1fc70 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
1fc80 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
1fc90 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
1fca0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
1fcb0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
1fcc0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
1fcd0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
1fce0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1fcf0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
1fd00 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
1fd10 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
1fd20 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
1fd30 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
1fd40 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
1fd50 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
1fd60 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
1fd70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1fd80 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1fd90 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1fda0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1fdb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1fdc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1fdd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1fde0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1fdf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1fe00 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1fe10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1fe20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1fe30 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
1fe40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
1fe50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fe60 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
1fe70 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
1fe80 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
1fe90 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
1fea0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
1feb0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
1fec0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
1fed0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
1fee0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
1fef0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
1ff00 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
1ff10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
1ff20 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1ff30 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
1ff40 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1ff50 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
1ff60 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
1ff70 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1ff80 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
1ff90 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
1ffa0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
1ffb0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
1ffc0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
1ffd0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
1ffe0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1fff0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20000 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
20010 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20020 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
20030 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20040 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20050 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
20060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20070 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
20080 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
20090 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
200a0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
200b0 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
200c0 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
200d0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
200e0 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
200f0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
20100 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
20110 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
20120 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
20130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20140 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
20150 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
20160 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
20170 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
20180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20190 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
201a0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
201b0 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
201c0 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
201d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
201e0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
201f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
20200 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
20210 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
20220 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
20230 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
20240 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20250 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
20260 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
20270 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
20280 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
20290 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
202a0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
202b0 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
202c0 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
202d0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
202e0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
202f0 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74  UPDATE])..*/.int
20300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20310 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
20320 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
20330 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
20340 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
20350 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
20360 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
20370 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
20380 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
20390 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
203a0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
203b0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
203c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
203d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
203e0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
203f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
20400 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
20410 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
20420 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
20430 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
20440 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
20450 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
20460 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
20470 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
20480 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
20490 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
204a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
204b0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
204c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
204d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
204e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
204f0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
20500 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
20510 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
20520 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
20530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
20540 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
20550 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
20560 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
20570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20580 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
20590 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
205a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
205b0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
205c0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
205d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
205e0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
205f0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
20600 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
20610 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
20620 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
20630 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
20640 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
20650 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
20660 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
20670 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
20680 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
20690 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
206a0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
206b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
206c0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
206d0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
206e0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
206f0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
20700 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
20710 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
20720 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
20730 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
20740 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
20750 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
20760 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
20770 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
20780 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
20790 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
207a0 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
207b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
207c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
207d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
207e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
207f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20800 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
20810 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
20820 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
20830 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
20840 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
20850 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
20860 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
20870 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
20880 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
20890 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
208a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
208b0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
208c0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
208d0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
208e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
208f0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
20900 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20910 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
20920 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
20930 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
20940 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
20950 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
20960 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
20970 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
20980 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
20990 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
209a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
209b0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
209c0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
209d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
209e0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
209f0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
20a00 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
20a10 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
20a20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20a30 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
20a40 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
20a50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
20a60 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
20a70 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
20a80 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
20a90 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
20aa0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
20ab0 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
20ac0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
20ad0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
20ae0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
20af0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
20b00 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
20b10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
20b20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
20b30 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
20b40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20b50 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
20b60 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
20b70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
20b80 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
20b90 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
20ba0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
20bb0 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
20bc0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
20bd0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
20be0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
20bf0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
20c00 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
20c10 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
20c20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
20c30 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
20c40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
20c50 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
20c60 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
20c70 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
20c80 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
20c90 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
20ca0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
20cb0 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
20cc0 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
20cd0 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
20ce0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20cf0 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
20d00 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
20d10 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
20d20 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
20d30 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
20d40 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
20d50 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
20d60 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
20d70 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
20d80 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
20d90 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
20da0 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
20db0 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
20dc0 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
20dd0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
20de0 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
20df0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
20e00 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
20e10 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
20e20 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
20e30 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
20e40 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
20e50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
20e60 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
20e70 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
20e80 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
20e90 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
20ea0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
20eb0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
20ec0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
20ed0 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
20ee0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
20ef0 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
20f00 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
20f10 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
20f20 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
20f30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
20f40 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
20f50 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
20f60 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
20f70 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
20f80 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
20f90 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
20fa0 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
20fb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
20fc0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
20fd0 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
20fe0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
20ff0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
21000 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
21010 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
21020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
21030 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
21040 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21050 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21060 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
21070 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
21080 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21090 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
210a0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
210b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
210c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
210d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
210e0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
210f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21100 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
21110 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
21120 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
21130 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21140 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21150 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
21160 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
21170 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
21180 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
21190 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
211a0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
211b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
211c0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
211d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
211e0 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
211f0 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
21200 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
21210 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
21220 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
21230 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
21240 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
21250 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
21260 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
21270 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
21280 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
21290 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
212a0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
212b0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
212c0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
212d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
212e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
212f0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
21300 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
21310 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
21320 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
21330 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
21340 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
21350 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
21360 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
21370 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
21380 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
21390 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
213a0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
213b0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
213c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
213d0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
213e0 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
213f0 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
21400 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
21410 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
21420 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
21430 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
21440 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
21450 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
21460 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
21470 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
21480 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
21490 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
214a0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
214b0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
214c0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
214d0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
214e0 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
214f0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
21500 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
21510 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
21520 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
21530 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
21540 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
21550 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
21560 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
21570 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
21580 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
21590 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
215a0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
215b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
215c0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
215d0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
215e0 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
215f0 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
21600 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
21610 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
21620 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
21630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
21640 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
21650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
21660 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
21670 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
21680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
21690 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
216a0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
216b0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
216c0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
216d0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
216e0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
216f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21700 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21710 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
21720 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
21730 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
21740 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
21750 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
21760 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
21770 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
21780 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
21790 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
217a0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
217b0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
217c0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
217d0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
217e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
217f0 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
21800 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
21810 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
21820 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
21830 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
21840 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
21850 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
21860 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
21870 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21880 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
21890 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
218a0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
218b0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
218c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
218d0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
218e0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
218f0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
21900 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
21910 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
21920 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
21930 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
21940 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
21950 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
21960 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
21970 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
21980 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
21990 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
219a0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
219b0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
219c0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
219d0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
219e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
219f0 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
21a00 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
21a10 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
21a20 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
21a30 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
21a40 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
21a50 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
21a60 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
21a70 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
21a80 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
21a90 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
21aa0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
21ab0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
21ac0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
21ad0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
21ae0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21af0 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
21b00 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
21b10 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
21b20 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
21b30 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
21b40 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
21b50 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
21b60 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
21b70 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
21b80 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
21b90 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
21ba0 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
21bb0 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
21bc0 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
21bd0 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
21be0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
21bf0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
21c00 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
21c10 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
21c20 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
21c30 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
21c40 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
21c50 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
21c60 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
21c70 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
21c80 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
21c90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
21ca0 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
21cb0 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
21cc0 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
21cd0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
21ce0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
21cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
21d00 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
21d10 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
21d20 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
21d30 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
21d40 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
21d50 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
21d60 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
21d70 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
21d80 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
21d90 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
21da0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
21db0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
21dc0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
21dd0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
21de0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
21df0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
21e00 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
21e10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
21e20 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
21e30 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
21e40 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
21e50 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
21e60 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
21e70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
21e80 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
21e90 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
21ea0 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
21eb0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
21ec0 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
21ed0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
21ee0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
21ef0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
21f00 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
21f10 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
21f20 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
21f30 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
21f40 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
21f50 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
21f60 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
21f70 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
21f80 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
21f90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21fa0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
21fb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21fc0 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
21fd0 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
21fe0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
21ff0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
22000 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
22010 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
22020 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
22030 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
22040 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
22050 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
22060 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
22070 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
22080 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
22090 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
220a0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
220b0 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
220c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
220d0 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
220e0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
220f0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
22100 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
22110 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
22120 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
22130 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
22140 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
22150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22160 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
22170 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
22180 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
22190 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
221a0 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
221b0 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
221c0 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
221d0 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
221e0 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20  .6.23.1, it was 
221f0 72 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65  required.** afte
22200 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
22210 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
22220 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
22230 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a  QLITE_ROW] that.
22240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
22250 74 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62  t()] be called b
22260 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
22270 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
22280 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
22290 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
222a0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
222b0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68  3_reset()] in th
222c0 69 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20  is way would.** 
222d0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
222e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
222f0 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  urn from sqlite3
22300 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
22310 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33  ter.** version 3
22320 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
22330 5f 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61  _step() began ca
22340 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
22350 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f  eset()] .** auto
22360 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
22370 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
22380 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
22390 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
223a0 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62  USE].  .**.** <b
223b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
223c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
223d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
223e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
223f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
22400 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
22410 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
22420 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
22430 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
22440 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
22450 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
22460 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
22470 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
22480 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
22490 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
224a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
224b0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
224c0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
224d0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
224e0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
224f0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
22500 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
22510 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
22520 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
22530 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
22540 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
22550 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
22560 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
22570 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
22580 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
22590 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
225a0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
225b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
225c0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
225d0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
225e0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
225f0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
22600 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
22610 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
22620 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
22630 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
22640 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
22650 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
22660 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
22670 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
22680 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
22690 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
226a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
226b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
226c0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
226d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
226e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
226f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
22700 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
22710 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
22720 63 6f 75 6e 74 28 50 29 20 74 68 65 20 6e 75 6d  count(P) the num
22730 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22740 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68 65 20  n the.** of the 
22750 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
22760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22770 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] P..*/.int sql
22780 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
22790 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
227a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
227b0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
227c0 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
227d0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
227e0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
227f0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
22800 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
22810 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
22820 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
22830 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
22840 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
22850 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
22860 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
22870 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
22880 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
22890 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
228a0 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
228b0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
228c0 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
228d0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
228e0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
228f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
22900 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
22910 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
22920 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
22930 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
22940 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
22950 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
22960 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
22970 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
22980 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
22990 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
229a0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
229b0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
229c0 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
229d0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
229e0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
229f0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
22a00 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
22a10 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
22a20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
22a30 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
22a40 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
22a50 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
22a60 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
22a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
22a80 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
22a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
22aa0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
22ab0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
22ac0 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
22ad0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
22ae0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
22af0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
22b00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22b10 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
22b20 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
22b30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
22b40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22b50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
22b60 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
22b70 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
22b80 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
22b90 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
22ba0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
22bb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
22bc0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
22bd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22be0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
22bf0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
22c00 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
22c10 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
22c20 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
22c30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22c40 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
22c50 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
22c60 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
22c70 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
22c80 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
22c90 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
22ca0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
22cb0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
22cc0 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
22cd0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
22ce0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
22cf0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
22d00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
22d10 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
22d20 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
22d30 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
22d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
22d50 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
22d60 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
22d70 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
22d80 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
22d90 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
22da0 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
22db0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
22dc0 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
22dd0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
22de0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22df0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
22e00 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
22e10 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
22e20 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
22e30 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
22e40 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
22e50 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
22e60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22e70 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
22e80 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
22e90 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
22ea0 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
22eb0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
22ec0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
22ed0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
22ee0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
22ef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22f00 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
22f10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
22f20 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
22f30 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
22f40 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
22f50 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22f60 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
22f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22f80 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
22f90 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
22fa0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
22fb0 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
22fc0 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
22fd0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
22fe0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
22ff0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
23000 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
23010 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23040 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
23050 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
23060 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
23070 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
23080 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
23090 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
230a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
230b0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
230c0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
230d0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
230e0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
230f0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
23100 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
23110 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
23120 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
23130 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
23140 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
23150 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
23160 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
23170 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
23180 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
23190 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
231a0 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
231b0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
231c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
231d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
231e0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
231f0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
23200 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
23210 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
23220 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
23230 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23240 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
23250 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
23260 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
23270 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
23280 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
23290 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
232a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
232b0 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
232c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
232d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
232e0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
232f0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
23300 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
23310 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
23320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23330 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
23340 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
23350 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
23360 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
23370 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
23380 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
23390 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
233a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
233b0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
233c0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
233d0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
233e0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
233f0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
23400 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
23410 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23420 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
23430 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ing..** ^The val
23440 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
23450 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
23460 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23470 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
23480 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
23490 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
234a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
234b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
234c0 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
234d0 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
234e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
234f0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
23500 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
23510 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23520 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
23530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
23540 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
23550 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
23560 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
23570 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
23580 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
23590 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
235a0 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
235b0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
235c0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
235d0 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
235e0 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
235f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
23600 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
23610 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
23620 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
23630 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
23640 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
23650 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
23660 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
23670 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23680 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
23690 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72  F-8..** ^The zer
236a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
236b0 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
236c0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
236d0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
236e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
236f0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
23700 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
23710 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23720 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
23730 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
23740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23750 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
23760 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
23770 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
23780 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23790 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
237a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
237b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
237c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
237d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
237e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
237f0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
23800 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
23810 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
23820 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
23830 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
23840 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
23850 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
23860 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
23870 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
23880 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
23890 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
238a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
238b0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
238c0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
238d0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
238e0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
238f0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
23900 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
23910 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
23920 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
23930 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
23940 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
23950 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
23960 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
23970 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
23980 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
23990 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
239a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
239b0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
239c0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
239d0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
239e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
239f0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
23a00 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
23a10 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
23a20 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
23a30 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
23a40 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
23a50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
23a60 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
23a70 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
23a80 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
23a90 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
23aa0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
23ab0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
23ac0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
23ad0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
23ae0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
23af0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
23b00 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
23b10 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23b20 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
23b30 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
23b40 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
23b50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
23b60 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
23b70 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
23b80 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
23b90 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
23ba0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
23bb0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
23bc0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
23bd0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
23be0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
23bf0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
23c00 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
23c10 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
23c20 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23c30 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
23c40 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
23c50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23c60 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
23c70 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
23c80 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
23c90 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
23ca0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
23cb0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
23cc0 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
23cd0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
23ce0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
23cf0 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
23d00 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
23d10 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
23d20 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
23d30 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
23d40 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
23d50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
23d60 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
23d70 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
23d80 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23d90 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
23da0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
23db0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
23dc0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
23dd0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
23de0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
23df0 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
23e00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
23e10 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
23e20 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
23e30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
23e40 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
23e50 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
23e60 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
23e70 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
23e80 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
23e90 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
23ea0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
23eb0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
23ec0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
23ed0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
23ee0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
23ef0 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
23f00 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
23f10 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
23f20 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
23f30 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
23f40 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
23f50 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
23f60 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
23f70 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
23f80 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
23f90 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
23fa0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 77 68 65  * ^Note that whe
23fb0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
23fc0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
23fd0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
23fe0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
23ff0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24000 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
24010 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
24020 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
24030 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
24040 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
24050 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63  ted..** ^(Type c
24060 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
24070 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
24080 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
24090 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
240a0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
240b0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
240c0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
240d0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
240e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
240f0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
24100 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
24110 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
24120 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
24130 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
24140 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
24150 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
24160 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
24170 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
24180 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
24190 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
241a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
241b0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
241c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
241d0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
241e0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
241f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
24200 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
24210 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
24220 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
24230 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
24240 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
24250 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
24260 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
24270 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
24280 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
24290 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
242a0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
242b0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
242c0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
242d0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
242e0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
242f0 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
24300 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
24310 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
24320 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
24330 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
24340 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
24350 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
24360 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
24370 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
24380 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c  er points to wil
24390 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
243a0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
243b0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
243c0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
243d0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
243e0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
243f0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
24400 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
24410 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
24420 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
24430 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
24440 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ted..**.** ^(The
24450 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
24460 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
24470 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
24480 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
24490 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
244a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
244b0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
244c0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
244d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
244e0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
244f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
24500 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
24510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24520 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
24530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24540 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
24550 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
24560 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
24570 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
24580 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
24590 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  /li>.** </ul>)^.
245a0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
245b0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
245c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
245d0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
245e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
245f0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
24600 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24610 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
24620 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
24630 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
24640 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
24650 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
24660 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
24670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24680 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
24690 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
246a0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
246b0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
246c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
246d0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
246e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
246f0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
24700 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
24710 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
24720 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
24730 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
24740 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
24750 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
24760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24770 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
24780 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
24790 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
247a0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
247b0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
247c0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
247d0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
247e0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
247f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24800 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
24810 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
24820 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
24830 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
24840 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
24850 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
24860 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
24870 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
24880 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
24890 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
248a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
248b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
248c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
248d0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
248e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
248f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
24900 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
24910 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
24920 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
24930 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
24940 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
24950 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
24960 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
24970 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
24980 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
24990 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
249a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
249b0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
249c0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
249d0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
249e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
249f0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
24a00 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
24a10 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
24a20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
24a30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
24a40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24a50 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
24a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24a70 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
24a80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
24a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24aa0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
24ab0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24ac0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
24ad0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
24ae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24af0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
24b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
24b10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24b20 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
24b30 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
24b40 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
24b50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24b60 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
24b70 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
24b80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
24b90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24ba0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
24bb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24bc0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
24bd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24be0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24bf0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
24c00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24c10 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
24c20 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
24c30 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
24c40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24c50 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
24c60 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
24c70 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
24c80 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
24c90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
24ca0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
24cb0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
24cc0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
24cd0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24ce0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
24cf0 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
24d00 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
24d10 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
24d20 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
24d30 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
24d40 64 2e 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e  d. ^If execution
24d50 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
24d60 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
24d70 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
24d80 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
24d90 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
24da0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
24db0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
24dc0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
24dd0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
24de0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
24df0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
24e00 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20  tatement].  ^If 
24e10 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
24e20 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
24e30 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
24e40 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
24e50 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
24e60 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
24e70 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
24e80 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
24e90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
24ea0 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
24eb0 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61  ^Incomplete upda
24ec0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
24ed0 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
24ee0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
24ef0 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
24f00 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
24f10 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
24f20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
24f30 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
24f40 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f  QLITE_ABORT]..*/
24f50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
24f60 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
24f70 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
24f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
24f90 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
24fa0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
24fb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24fc0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
24fd0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
24fe0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
24ff0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
25000 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
25010 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
25020 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
25030 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
25040 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
25050 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
25060 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
25070 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
25080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
25090 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
250a0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
250b0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
250c0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
250d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
250e0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
250f0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
25100 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
25110 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
25120 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
25130 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25140 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
25150 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
25160 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
25170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
25180 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
25190 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
251a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
251b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
251c0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
251d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
251e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
251f0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
25200 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
25210 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
25220 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
25230 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
25240 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
25250 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
25260 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
25270 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
25280 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25290 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
252a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
252b0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
252c0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
252d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
252e0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
252f0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
25300 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
25310 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
25320 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
25330 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
25340 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
25350 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
25360 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
25370 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
25380 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
25390 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
253a0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
253b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
253c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
253d0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
253e0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
253f0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
25400 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
25410 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
25420 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
25430 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
25440 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
25450 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
25460 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
25470 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
25480 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
25490 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
254a0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
254b0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
254c0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
254d0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
254e0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
254f0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
25500 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
25510 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
25520 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
25530 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
25540 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
25550 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  nce between the.
25560 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  ** two is that t
25570 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25580 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ter, the name of
25590 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
255a0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
255b0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
255c0 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20  ed in UTF-8 for 
255d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
255e0 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
255f0 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  F-16.** for sqli
25600 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25610 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ion16()..**.** ^
25620 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
25630 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
25640 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25650 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
25660 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
25670 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
25680 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
25690 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
256a0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
256b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
256c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
256d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
256e0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
256f0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
25700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25710 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
25720 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
25730 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
25740 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
25750 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
25760 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
25770 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
25780 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
25790 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
257a0 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
257b0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
257c0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
257d0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
257e0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
257f0 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
25800 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 5e  * characters.  ^
25810 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
25820 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
25830 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
25840 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
25850 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52  lt in [SQLITE_ER
25860 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72  ROR] being retur
25870 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
25880 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25890 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
258a0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
258b0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
258c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
258d0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
258e0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
258f0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
25900 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25910 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
25920 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
25930 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
25940 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
25950 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
25960 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
25970 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
25980 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
25990 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
259a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
259b0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
259c0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
259d0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
259e0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
259f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
25a00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
25a10 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
25a20 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
25a30 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
25a40 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
25a50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
25a60 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
25a70 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
25a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
25a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
25aa0 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
25ab0 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
25ac0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
25ad0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
25ae0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
25af0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
25b00 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
25b10 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
25b20 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
25b30 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
25b40 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
25b50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
25b60 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
25b70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25b80 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
25b90 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
25ba0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
25bb0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
25bc0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
25bd0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
25be0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
25bf0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
25c00 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
25c10 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
25c20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
25c30 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
25c40 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
25c50 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
25c60 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
25c70 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
25c80 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
25c90 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
25ca0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
25cb0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
25cc0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
25cd0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
25ce0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
25cf0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
25d00 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
25d10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
25d20 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
25d30 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
25d40 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
25d50 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
25d60 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
25d70 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
25d80 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
25d90 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
25da0 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
25db0 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
25dc0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
25dd0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
25de0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
25df0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
25e00 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25e10 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
25e20 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
25e30 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
25e40 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
25e50 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
25e60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
25e70 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
25e80 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
25e90 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
25ea0 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
25eb0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
25ec0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
25ed0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
25ee0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
25ef0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
25f00 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
25f10 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
25f20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
25f30 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
25f40 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
25f50 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
25f60 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
25f70 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
25f80 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
25f90 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
25fa0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  acks..**.** ^It 
25fb0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
25fc0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
25fd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25fe0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
25ff0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
26000 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
26010 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
26020 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
26030 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
26040 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
26050 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
26060 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
26070 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
26080 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
26090 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
260a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
260b0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
260c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
260d0 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
260e0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
260f0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
26100 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
26110 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
26120 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
26130 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
26140 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
26150 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
26160 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
26170 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
26180 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
26190 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
261a0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
261b0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
261c0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
261d0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
261e0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
261f0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
26200 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
26210 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
26220 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
26230 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
26240 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
26250 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
26260 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
26270 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
26280 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
26290 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
262a0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
262b0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
262c0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
262d0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
262e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
262f0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68  unctions..** ^Th
26300 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
26310 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26320 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
26330 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
26340 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
26350 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
26360 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
26370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
26380 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
26390 0a 2a 2a 20 5e 53 75 62 73 65 71 75 65 6e 74 20  .** ^Subsequent 
263a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
263b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66  ned functions of
263c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f   the same name o
263d0 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a  nly override .**
263e0 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69   prior applicati
263f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26400 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e  ions that are an
26410 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72   exact match for
26420 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
26430 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  f parameters and
26440 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64   preferred encod
26450 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ing..**.** ^An a
26460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26470 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
26480 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
26490 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
264a0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
264b0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
264c0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
264d0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
264e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
264f0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
26500 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
26510 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
26520 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
26530 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
26540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
26550 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
26560 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
26570 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
26580 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
26590 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
265a0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
265b0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
265c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
265d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
265e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
265f0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
26600 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
26610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
26620 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
26630 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
26640 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
26650 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26660 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
26670 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
26680 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
26690 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
266a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
266b0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
266c0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
266d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
266e0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
266f0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
26700 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
26710 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
26720 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
26730 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
26740 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
26750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26760 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
26770 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
26780 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
26790 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
267a0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
267b0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
267c0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
267d0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
267e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
267f0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
26800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
26810 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
26820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
26830 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
26840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
26850 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
26860 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
26870 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
26880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
26890 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
268a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
268b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
268c0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
268d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
268e0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
268f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
26900 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
26910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
26920 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
26930 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
26940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
26950 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
26960 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
26970 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
26980 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
26990 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
269a0 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
269b0 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
269c0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
269d0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
269e0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
269f0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
26a00 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
26a10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
26a20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
26a30 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
26a40 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
26a50 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
26a60 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
26a70 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
26a80 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
26a90 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
26aa0 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
26ab0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26ac0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
26ad0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
26ae0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
26af0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26b00 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
26b10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
26b20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26b30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
26b40 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
26b50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
26b60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
26b70 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26b80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
26b90 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
26ba0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
26bb0 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
26bc0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
26bd0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
26be0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
26bf0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
26c00 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
26c10 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
26c20 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
26c30 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
26c40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26c50 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
26c60 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
26c70 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
26c80 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
26c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
26ca0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
26cb0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
26cc0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
26cd0 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
26ce0 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
26cf0 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
26d00 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
26d10 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
26d20 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
26d30 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
26d40 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
26d50 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
26d60 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
26d70 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
26d80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
26d90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26da0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26db0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
26dc0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
26dd0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
26de0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
26df0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
26e00 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
26e10 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
26e20 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
26e30 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
26e40 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
26e50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26e60 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
26e70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
26e80 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
26e90 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
26ea0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
26eb0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
26ec0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
26ed0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
26ee0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
26ef0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26f00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
26f10 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
26f20 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
26f30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26f40 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
26f50 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
26f60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
26f70 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
26f80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26f90 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
26fa0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
26fb0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
26fc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
26fd0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
26fe0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
26ff0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
27000 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
27010 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
27020 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
27030 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
27040 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27050 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
27060 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
27070 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
27080 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
27090 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
270a0 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
270b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
270c0 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
270d0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
270e0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
270f0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
27100 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
27110 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
27120 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
27130 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
27140 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
27150 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
27160 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
27170 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
27180 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
27190 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
271a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
271b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
271c0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
271d0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
271e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
271f0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
27200 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
27210 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
27220 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
27230 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
27240 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
27250 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
27260 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
27270 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
27280 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
27290 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
272a0 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
272b0 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
272c0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
272d0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
272e0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
272f0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
27300 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
27310 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
27320 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
27330 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
27340 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
27350 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
27360 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
27370 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
27380 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
27390 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
273a0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
273b0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
273c0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
273d0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
273e0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
273f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27400 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
27410 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27420 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
27430 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
27440 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
27450 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
27460 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
27470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27480 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
27490 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
274a0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
274b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
274c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
274d0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
274e0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
274f0 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
27500 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27510 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
27520 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
27530 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
27540 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
27550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
27560 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
27570 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27580 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
27590 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
275a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
275b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
275c0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
275d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
275e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
275f0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
27600 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
27610 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
27620 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
27630 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
27640 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
27650 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
27660 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
27670 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
27680 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
27690 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
276a0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
276b0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
276c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
276d0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
276e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
276f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27700 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
27710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27730 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
27740 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27750 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
27760 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
27770 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
27780 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
27790 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
277a0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
277b0 2a 20 49 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20  * Implementions 
277c0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
277d0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
277e0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
277f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
27800 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
27810 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
27820 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
27830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
27840 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
27850 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
27860 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
27870 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
27880 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
27890 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
278a0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
278b0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
278c0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
278d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
278e0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
278f0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
27900 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
27910 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
27920 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27930 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
27940 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
27950 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
27960 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
27970 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
27980 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
27990 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
279a0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
279b0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
279c0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
279d0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
279e0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
279f0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
27a00 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
27a10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
27a20 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
27a30 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
27a40 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
27a50 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
27a60 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
27a70 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
27a80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
27a90 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
27aa0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
27ab0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
27ac0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
27ad0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
27ae0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27af0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
27b00 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
27b10 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
27b20 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
27b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27b40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27b50 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
27b60 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
27b70 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
27b80 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
27b90 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
27ba0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
27bb0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
27bc0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
27bd0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
27be0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
27bf0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27c00 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
27c10 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
27c20 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
27c30 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
27c40 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
27c50 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
27c60 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
27c70 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
27c80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27c90 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
27ca0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
27cb0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
27cc0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
27cd0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
27ce0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
27cf0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
27d00 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
27d10 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
27d20 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
27d30 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
27d40 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
27d50 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
27d60 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
27d70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
27d80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
27d90 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
27da0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
27db0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
27dc0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
27dd0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
27de0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
27df0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
27e00 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
27e10 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
27e20 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
27e30 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
27e40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
27e50 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
27e60 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27e70 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
27e80 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
27e90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
27ea0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
27eb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
27ec0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
27ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
27ee0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
27ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
27f00 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
27f10 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
27f20 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
27f30 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
27f40 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
27f50 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
27f60 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
27f70 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
27f80 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
27f90 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
27fa0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27fb0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
27fc0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
27fd0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
27fe0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
27ff0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
28000 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
28010 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
28020 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
28030 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
28040 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
28050 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
28060 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
28070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28080 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
28090 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
280a0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
280b0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
280c0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
280d0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
280e0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
280f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
28100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
28110 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
28120 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28130 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
28140 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
28150 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
28160 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
28170 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
28180 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
28190 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
281a0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
281b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
281c0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
281d0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
281e0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
281f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28200 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
28210 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
28220 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
28230 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
28240 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
28250 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
28260 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
28270 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
28280 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
28290 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
282a0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
282b0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
282c0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
282d0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
282e0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
282f0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
28300 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
28310 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
28320 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
28330 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
28340 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
28350 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
28360 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
28370 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
28380 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
28390 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
283a0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
283b0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
283c0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
283d0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
283e0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
283f0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
28400 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
28410 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
28420 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
28430 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
28440 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
28450 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
28460 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
28470 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
28480 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
28490 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
284a0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
284b0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
284c0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
284d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
284e0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
284f0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
28500 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
28510 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
28520 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
28530 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
28540 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28550 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
28560 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28570 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
28580 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
28590 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
285a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
285b0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
285c0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
285d0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
285e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
285f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28600 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
28610 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
28620 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
28630 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
28640 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
28650 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
28660 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
28670 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
28680 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
28690 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
286a0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
286b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
286c0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
286d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
286e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
286f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
28700 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
28710 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
28720 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
28730 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
28740 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
28750 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
28760 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
28770 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28780 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
28790 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
287a0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
287b0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
287c0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
287d0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
287e0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
287f0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
28800 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
28810 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
28820 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
28830 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
28840 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
28850 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28860 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
28870 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
28880 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
28890 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
288a0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
288b0 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
288c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
288d0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
288e0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
288f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
28900 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
28910 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
28920 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
28930 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
28940 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
28950 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
28960 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
28970 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
28980 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
28990 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
289a0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
289b0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
289c0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
289d0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
289e0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
289f0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
28a00 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
28a10 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
28a20 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
28a30 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
28a40 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
28a50 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
28a60 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
28a70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28a80 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
28a90 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
28aa0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
28ab0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
28ac0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
28ad0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
28ae0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
28af0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
28b00 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
28b10 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
28b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
28b30 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
28b40 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
28b50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28b60 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
28b70 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
28b80 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
28b90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
28ba0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
28bb0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
28bc0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
28bd0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
28be0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
28bf0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
28c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28c10 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
28c20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
28c30 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
28c40 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
28c50 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
28c60 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
28c70 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
28c80 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
28c90 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
28ca0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
28cb0 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
28cc0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
28cd0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
28ce0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
28cf0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
28d00 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
28d10 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
28d20 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
28d30 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
28d40 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
28d50 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
28d60 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
28d70 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
28d80 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
28d90 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
28da0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
28db0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
28dc0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
28dd0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
28de0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
28df0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
28e00 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
28e10 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
28e20 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
28e30 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
28e40 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
28e50 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
28e60 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
28e70 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
28e80 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
28e90 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
28ea0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
28eb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28ec0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
28ed0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
28ee0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
28ef0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
28f00 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
28f10 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
28f20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
28f30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
28f40 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
28f50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
28f60 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
28f70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
28f80 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
28f90 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
28fa0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
28fb0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
28fc0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
28fd0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
28fe0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
28ff0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
29000 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
29010 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
29020 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
29030 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
29040 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
29050 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
29060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29070 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
29080 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29090 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
290a0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
290b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
290c0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
290d0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
290e0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
290f0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
29100 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
29110 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
29120 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
29130 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
29140 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
29150 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29160 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
29170 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
29180 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
29190 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
291a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
291b0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
291c0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
291d0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
291e0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
291f0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
29200 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
29210 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
29220 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29230 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
29240 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
29250 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
29260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29270 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29280 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
29290 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
292a0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
292b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
292c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
292d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
292e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
292f0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
29300 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
29310 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
29320 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
29330 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
29340 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
29350 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
29360 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
29370 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
29380 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
29390 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
293a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
293b0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
293c0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
293d0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
293e0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
293f0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
29400 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
29410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29420 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
29430 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
29440 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
29450 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
29460 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
29470 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
29480 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
29490 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
294a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
294b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
294c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
294d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
294e0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
294f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
29500 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
29510 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
29520 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
29530 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
29540 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
29550 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29560 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
29570 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
29580 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
29590 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
295a0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
295b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
295c0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
295d0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
295e0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
295f0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
29600 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
29610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29620 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
29630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29640 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
29650 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
29660 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
29670 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
29680 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
29690 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
296a0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
296b0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
296c0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
296d0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
296e0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
296f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
29700 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29710 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
29720 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
29730 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
29740 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
29750 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
29760 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
29770 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
29780 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
29790 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
297a0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
297b0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
297c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
297d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
297e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
297f0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
29800 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
29810 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
29820 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
29830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
29840 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
29850 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
29860 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
29870 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
29880 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
29890 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
298a0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
298b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
298c0 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
298d0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
298e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
298f0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
29900 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
29910 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
29920 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
29930 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29940 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
29950 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
29960 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
29970 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29980 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29990 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
299a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
299b0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
299c0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
299d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
299e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
299f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29a00 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
29a10 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
29a20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29a30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29a40 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
29a50 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
29a60 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
29a70 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
29a80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29a90 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
29aa0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29ab0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
29ac0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
29ad0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29ae0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
29af0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29b10 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
29b20 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
29b30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29b40 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
29b50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29b60 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
29b70 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
29b80 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
29b90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29ba0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
29bb0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
29bc0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
29bd0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
29be0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
29bf0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
29c00 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
29c10 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
29c20 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
29c30 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
29c40 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
29c50 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
29c60 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
29c70 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
29c80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
29c90 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
29ca0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
29cb0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
29cc0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
29cd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29ce0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29cf0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
29d00 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
29d10 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
29d20 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
29d30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
29d40 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
29d50 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
29d60 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
29d70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29d90 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
29da0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
29db0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
29dc0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
29dd0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
29de0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
29df0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
29e00 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
29e10 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
29e20 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
29e30 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
29e40 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
29e50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29e70 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
29e80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
29e90 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
29ea0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
29eb0 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
29ec0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
29ed0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
29ee0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
29ef0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
29f00 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
29f10 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
29f20 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
29f30 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
29f40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29f50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29f60 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
29f70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
29f80 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
29f90 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
29fa0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
29fb0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
29fc0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
29fd0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
29fe0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
29ff0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2a000 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2a010 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2a020 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
2a030 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2a040 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
2a050 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
2a060 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2a070 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2a080 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2a090 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2a0a0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2a0b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2a0c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2a0d0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2a0e0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2a0f0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2a100 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2a110 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a120 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2a130 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2a140 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2a150 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2a160 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2a170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a180 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2a190 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2a1a0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2a1b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a1c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a1d0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2a1e0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2a1f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2a200 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2a210 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2a220 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
2a230 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a240 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2a250 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2a260 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
2a270 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
2a280 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2a290 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2a2a0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2a2b0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2a2c0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2a2d0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2a2e0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2a2f0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2a300 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
2a310 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a320 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
2a330 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
2a340 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
2a350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a360 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
2a370 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
2a380 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
2a390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a3a0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
2a3b0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
2a3c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
2a3d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2a3e0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
2a3f0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
2a400 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
2a410 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2a420 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2a430 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2a440 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
2a450 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2a460 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2a470 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2a480 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a490 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2a4a0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
2a4b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2a4c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2a4d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2a4e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a4f0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
2a500 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
2a510 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
2a520 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a530 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
2a540 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2a550 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2a560 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a570 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2a580 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2a590 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2a5a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a5b0 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
2a5c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2a5d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a5e0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
2a5f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2a600 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a610 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
2a620 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a630 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2a640 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
2a650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a660 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2a670 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2a680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a690 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2a6a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a6b0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
2a6c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2a6d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a6e0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
2a6f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2a700 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
2a710 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a730 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
2a740 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2a750 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2a760 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a780 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2a790 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a7a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2a7b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2a7c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a7d0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2a7e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a7f0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2a800 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2a810 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a820 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
2a830 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2a840 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
2a850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2a860 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2a870 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2a880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a890 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2a8a0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2a8b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
2a8c0 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
2a8d0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
2a8e0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2a8f0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
2a900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2a910 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
2a920 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
2a930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2a940 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c   of the new coll
2a950 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2a960 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61  s specified as a
2a970 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
2a980 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2a990 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2a9a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
2a9b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2a9c0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
2a9d0 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
2a9e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a9f0 61 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61  ation16(). ^In a
2aa00 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
2aa10 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
2aa20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2aa30 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2aa40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2aa50 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
2aa60 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
2aa70 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
2aa80 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
2aa90 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51  UTF16LE], or [SQ
2aaa0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
2aab0 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
2aac0 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
2aad0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
2aae0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
2aaf0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
2ab00 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
2ab10 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
2ab20 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2ab30 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2ab40 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74  -endian, respect
2ab50 69 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74  ively. ^The.** t
2ab60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
2ab70 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
2ab80 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e  ITE_UTF16] to in
2ab90 64 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20  dicate that the 
2aba0 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63  routine.** expec
2abb0 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62  ts pointers to b
2abc0 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  e UTF-16 strings
2abd0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
2abe0 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68  yte order, or th
2abf0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61  e.** argument ca
2ac00 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  n be [SQLITE_UTF
2ac10 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74  16_ALIGNED] if t
2ac20 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  he.** the routin
2ac30 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  e expects pointe
2ac40 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72  rs to 16-bit wor
2ac50 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67  d aligned string
2ac60 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69  s.** of UTF-16 i
2ac70 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2ac80 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  e order..**.** A
2ac90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2aca0 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f  user supplied ro
2acb0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61  utine must be pa
2acc0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74  ssed as the fift
2acd0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  h.** argument.  
2ace0 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2acf0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
2ad00 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
2ad10 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2ad20 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
2ad30 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
2ad40 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
2ad50 2a 2a 20 5e 45 61 63 68 20 74 69 6d 65 20 74 68  ** ^Each time th
2ad60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
2ad70 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
2ad80 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
2ad90 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
2ada0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
2adb0 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
2adc0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
2add0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2ade0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2adf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ae00 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
2ae10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ae20 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  n16()..**.** ^Th
2ae30 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
2ae40 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
2ae50 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
2ae60 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
2ae70 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
2ae80 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
2ae90 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
2aea0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
2aeb0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
2aec0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
2aed0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
2aee0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
2aef0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2af00 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
2af10 72 65 67 69 73 74 65 72 65 64 2e 20 20 54 68 65  registered.  The
2af20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2af30 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
2af40 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
2af50 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
2af60 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
2af70 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ve if the first 
2af80 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2af90 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f  han,.** equal to
2afa0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
2afb0 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72  n the second str
2afc0 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
2afd0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
2afe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aff0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b000 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2b010 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2b020 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2b030 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
2b040 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
2b050 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2b060 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
2b070 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
2b080 6f 6e 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  on.  ^The destru
2b090 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
2b0a0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
2b0b0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
2b0c0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
2b0d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
2b0e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
2b0f0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
2b100 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
2b110 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2b120 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  v2()..** ^Collat
2b130 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
2b140 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
2b150 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2b160 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
2b170 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  e.** collation c
2b180 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
2b190 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64  s or when the [d
2b1a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b1b0 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a  on] is closed.**
2b1c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b1d0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
2b1e0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
2b1f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b200 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
2b210 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2b220 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
2b230 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b240 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
2b250 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2b260 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2b270 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2b280 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2b290 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2b2a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2b2b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2b2c0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2b2d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b2e0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
2b2f0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2b300 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2b310 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2b320 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2b330 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2b340 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2b350 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
2b360 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2b370 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
2b380 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b390 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2b3a0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
2b3b0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
2b3c0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2b3d0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2b3e0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2b3f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2b400 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2b410 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b420 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2b430 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2b440 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2b450 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2b460 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2b470 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2b480 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2b490 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2b4a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2b4b0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2b4c0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2b4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b4e0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
2b4f0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
2b500 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2b510 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b520 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2b530 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
2b540 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2b550 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2b560 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2b570 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2b580 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2b590 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2b5a0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2b5b0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2b5c0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2b5d0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
2b5e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2b5f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2b600 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
2b610 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
2b620 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2b630 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2b640 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
2b650 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
2b660 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
2b670 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
2b680 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
2b690 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
2b6a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2b6b0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2b6c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2b6d0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2b6e0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2b6f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2b700 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2b710 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2b720 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b730 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2b740 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b750 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2b760 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
2b770 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2b780 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2b790 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2b7a0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2b7b0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
2b7c0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2b7d0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
2b7e0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2b7f0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2b800 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2b810 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
2b820 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2b830 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2b840 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
2b850 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b860 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
2b870 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2b880 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2b890 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2b8a0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2b8b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b8c0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2b8d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b8e0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2b8f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2b900 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2b910 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2b920 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b930 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2b940 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2b950 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2b960 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2b970 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2b980 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2b990 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2b9a0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2b9b0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2b9c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2b9d0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2b9e0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2b9f0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
2ba00 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
2ba10 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2ba20 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2ba30 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2ba40 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2ba50 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2ba60 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2ba70 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2ba80 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2ba90 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2baa0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2bab0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2bac0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2bad0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bae0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2baf0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2bb00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2bb10 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2bb20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2bb30 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2bb40 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2bb50 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2bb60 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2bb70 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2bb80 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2bb90 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2bba0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2bbb0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2bbc0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2bbd0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2bbe0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2bbf0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2bc00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2bc10 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2bc20 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2bc30 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2bc40 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2bc50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2bc60 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2bc70 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2bc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bc90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2bca0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2bcb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2bcc0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2bcd0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2bce0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
2bcf0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2bd00 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
2bd10 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
2bd20 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2bd30 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
2bd40 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
2bd50 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2bd60 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2bd70 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2bd80 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2bd90 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2bda0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2bdb0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2bdc0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2bdd0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2bde0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2bdf0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2be00 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2be10 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2be20 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2be30 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2be40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2be50 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2be60 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
2be70 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2be80 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2be90 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2bea0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
2beb0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
2bec0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2bed0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
2bee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bef0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
2bf00 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
2bf10 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
2bf20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
2bf30 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
2bf40 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
2bf50 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
2bf60 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
2bf70 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  meter..**.** ^If
2bf80 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2bf90 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
2bfa0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
2bfb0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
2bfc0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
2bfd0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
2bfe0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
2bff0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
2c000 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
2c010 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65  cond. ^The numbe
2c020 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2c030 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2c040 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2c050 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2c060 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2c070 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2c080 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2c090 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2c0a0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2c0b0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2c0c0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2c0d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2c0e0 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
2c0f0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
2c100 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c110 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
2c120 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
2c130 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
2c140 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
2c150 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
2c160 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2c170 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
2c180 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
2c190 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
2c1a0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
2c1b0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
2c1c0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
2c1d0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
2c1e0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
2c1f0 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
2c200 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
2c210 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
2c220 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
2c230 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
2c240 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
2c250 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2c260 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
2c270 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
2c280 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
2c290 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
2c2a0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
2c2b0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2c2c0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2c2d0 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
2c2e0 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
2c2f0 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
2c300 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
2c310 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2c320 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2c330 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
2c340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2c350 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
2c360 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
2c370 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
2c380 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
2c390 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
2c3a0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
2c3b0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
2c3c0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
2c3d0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
2c3e0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
2c3f0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
2c400 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
2c410 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
2c420 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2c430 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2c440 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
2c450 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
2c460 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2c470 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
2c480 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2c490 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
2c4a0 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
2c4b0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2c4c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2c4d0 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
2c4e0 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
2c4f0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2c500 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
2c510 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
2c520 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
2c530 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
2c540 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
2c550 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2c560 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
2c570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
2c580 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
2c590 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
2c5a0 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
2c5b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2c5c0 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
2c5d0 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
2c5e0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
2c5f0 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
2c600 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
2c610 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
2c620 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
2c630 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c640 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c650 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
2c660 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
2c670 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2c680 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
2c690 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a   be avoided..*/.
2c6a0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
2c6b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
2c6c0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
2c6d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
2c6e0 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
2c6f0 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52  t Mode.** KEYWOR
2c700 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
2c710 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mode}.**.** ^The
2c720 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2c730 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
2c740 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
2c750 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
2c760 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
2c770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c780 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
2c790 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
2c7a0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
2c7b0 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  y.  ^Autocommit 
2c7c0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
2c7d0 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  fault..** ^Autoc
2c7e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
2c7f0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
2c800 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
2c810 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2c820 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
2c830 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
2c840 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
2c850 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
2c860 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
2c870 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
2c880 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
2c890 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
2c8a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
2c8b0 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
2c8c0 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
2c8d0 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
2c8e0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
2c8f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
2c900 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
2c910 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
2c920 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
2c930 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
2c940 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
2c950 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
2c960 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
2c970 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
2c980 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2c990 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
2c9a0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
2c9b0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
2c9c0 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
2c9d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  on..**.** If ano
2c9e0 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
2c9f0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
2ca00 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
2ca10 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2ca20 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
2ca30 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
2ca40 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
2ca50 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2ca60 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
2ca70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
2ca80 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
2ca90 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
2caa0 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
2cab0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
2cac0 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
2cad0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2cae0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
2caf0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
2cb00 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
2cb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cb20 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
2cb30 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
2cb40 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
2cb50 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
2cb60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cb70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2cb80 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2cb90 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
2cba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cbb0 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
2cbc0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2cbd0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
2cbe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2cbf0 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
2cc00 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
2cc10 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
2cc20 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2cc30 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2cc40 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74   place..*/.sqlit
2cc50 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
2cc60 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
2cc70 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2cc80 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
2cc90 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
2cca0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
2ccb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
2ccc0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ccd0 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
2cce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ccf0 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
2cd00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2cd10 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2cd20 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
2cd30 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
2cd40 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
2cd50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2cd60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2cd70 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
2cd80 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
2cd90 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2cda0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cdb0 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
2cdc0 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
2cdd0 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
2cde0 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
2cdf0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
2ce00 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
2ce10 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
2ce20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ce30 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
2ce40 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2ce50 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2ce60 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
2ce70 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
2ce80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2ce90 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
2cea0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
2ceb0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
2cec0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
2ced0 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
2cee0 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
2cef0 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
2cf00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2cf10 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2cf20 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2cf30 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2cf40 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
2cf50 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2cf60 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2cf70 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2cf80 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2cf90 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2cfa0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2cfb0 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
2cfc0 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
2cfd0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2cfe0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2cff0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2d000 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2d010 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d030 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2d040 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
2d050 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2d060 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2d070 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2d080 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2d090 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2d0a0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2d0b0 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
2d0c0 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
2d0d0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2d0e0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2d0f0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2d100 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2d110 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2d120 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2d130 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2d140 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
2d150 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
2d160 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
2d170 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2d180 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
2d190 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
2d1a0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
2d1b0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
2d1c0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
2d1d0 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
2d1e0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
2d1f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d200 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
2d210 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
2d220 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2d230 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
2d240 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
2d250 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
2d260 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d270 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2d280 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
2d290 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2d2a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
2d2b0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
2d2c0 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
2d2d0 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
2d2e0 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61   D..**.** The ca
2d2f0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
2d300 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2d310 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2d320 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2d330 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2d340 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2d350 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
2d360 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2d370 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2d380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d390 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2d3a0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2d3b0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2d3c0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2d3d0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2d3e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2d3f0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
2d400 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
2d410 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2d420 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
2d430 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d440 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2d450 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
2d460 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
2d470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d480 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
2d490 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
2d4a0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2d4b0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
2d4c0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2d4d0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2d4e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2d4f0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
2d500 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
2d510 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
2d520 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
2d530 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
2d540 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
2d550 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
2d560 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
2d570 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
2d580 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
2d590 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
2d5a0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2d5b0 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
2d5c0 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
2d5d0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
2d5e0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
2d5f0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
2d600 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
2d610 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
2d620 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
2d630 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
2d640 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
2d650 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
2d660 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
2d670 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
2d680 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
2d690 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
2d6a0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2d6b0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2d6c0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2d6d0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2d6e0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2d6f0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2d700 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2d710 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2d720 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
2d730 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2d740 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2d750 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2d760 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2d770 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2d780 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2d790 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2d7a0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
2d7b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  o the [sqlite3_u
2d7c0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
2d7d0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64  terface..*/.void
2d7e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
2d7f0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2d800 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
2d810 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
2d820 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2d830 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
2d840 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
2d850 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
2d860 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
2d870 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
2d880 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
2d890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
2d8a0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
2d8b0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2d8c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2d8d0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
2d8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d8f0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
2d900 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
2d910 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
2d920 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2d930 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
2d940 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2d950 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63  leted..** ^Any c
2d960 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2d970 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2d980 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
2d990 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d9a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d9b0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2d9c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  n..**.** ^The se
2d9d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2d9e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d9f0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
2da00 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
2da10 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2da20 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2da30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ed..** ^The firs
2da40 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2da50 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
2da60 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
2da70 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
2da80 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2da90 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20  hook()..** ^The 
2daa0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
2dab0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2dac0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
2dad0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
2dae0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
2daf0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
2db00 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
2db10 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
2db20 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
2db30 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2db40 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  ..** ^The third 
2db50 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
2db60 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
2db70 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
2db80 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
2db90 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2dba0 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2dbb0 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2dbc0 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e  row..** ^The fin
2dbd0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
2dbe0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
2dbf0 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
2dc00 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65  .** ^In the case
2dc10 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
2dc20 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
2dc30 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
2dc40 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
2dc50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64  .**.** ^(The upd
2dc60 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2dc70 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2dc80 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2dc90 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2dca0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2dcb0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2dcc0 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a  te_sequence).)^.
2dcd0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75  **.** ^In the cu
2dce0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
2dcf0 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65  tion, the update
2dd00 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20   hook.** is not 
2dd10 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70  invoked when dup
2dd20 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72  lication rows ar
2dd30 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73  e deleted becaus
2dd40 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43  e of an.** [ON C
2dd50 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e  ONFLICT | ON CON
2dd60 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63  FLICT REPLACE] c
2dd70 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20  lause.  ^Nor is 
2dd80 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2dd90 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
2dda0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2ddb0 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
2ddc0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
2ddd0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
2dde0 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
2ddf0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
2de00 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
2de10 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
2de20 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
2de30 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2de40 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
2de50 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
2de60 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
2de70 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
2de80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2de90 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
2dea0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2deb0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2dec0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2ded0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2dee0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2def0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2df00 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2df10 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2df20 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2df30 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2df40 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
2df50 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2df60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2df70 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2df80 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2df90 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2dfa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2dfb0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2dfc0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2dfd0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2dfe0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  h..**.** ^The sq
2dff0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2e000 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
2e010 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  n.** returns the
2e020 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
2e030 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2e040 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ll.** on the sam
2e050 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2e060 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
2e070 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
2e080 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a  rst call on D..*
2e090 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2e0a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
2e0b0 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73  t_hook()] and [s
2e0c0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2e0d0 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  hook()].** inter
2e0e0 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  faces..*/.void *
2e0f0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2e100 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
2e110 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2e120 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
2e130 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
2e140 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2e150 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
2e160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2e170 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2e180 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2e190 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  he.** KEYWORDS: 
2e1a0 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a  {shared cache}.*
2e1b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2e1c0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
2e1d0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
2e1e0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
2e1f0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
2e200 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
2e210 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
2e220 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e230 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
2e240 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
2e250 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
2e260 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2e270 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2e280 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
2e290 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
2e2a0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
2e2b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
2e2c0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
2e2d0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
2e2e0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
2e2f0 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
2e300 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
2e310 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
2e320 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
2e330 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2e340 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
2e350 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
2e360 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
2e370 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
2e380 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2e390 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
2e3a0 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
2e3b0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
2e3c0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
2e3d0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
2e3e0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2e3f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2e400 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2e410 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
2e420 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
2e430 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
2e440 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
2e450 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
2e460 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
2e470 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
2e480 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
2e490 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2e4a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
2e4b0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2e4c0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2e4d0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2e4e0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2e4f0 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
2e500 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
2e510 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
2e520 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
2e530 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
2e540 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
2e550 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
2e560 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
2e570 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
2e580 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2e590 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
2e5a0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
2e5b0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
2e5c0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
2e5d0 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
2e5e0 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
2e5f0 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e  ache Mode].*/.in
2e600 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
2e610 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
2e620 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e630 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
2e640 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
2e650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e660 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2e670 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
2e680 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
2e690 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
2e6a0 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
2e6b0 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
2e6c0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
2e6d0 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
2e6e0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
2e6f0 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65  se library.   Me
2e700 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
2e710 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
2e720 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
2e730 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
2e740 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
2e750 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
2e760 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  y..** ^sqlite3_r
2e770 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2e780 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e790 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
2e7a0 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77  ally freed,.** w
2e7b0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
2e7c0 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20  re or less than 
2e7d0 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
2e7e0 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sted..*/.int sql
2e7f0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e800 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
2e810 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
2e820 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
2e830 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
2e840 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
2e850 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
2e860 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
2e870 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
2e880 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
2e890 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
2e8a0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
2e8b0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
2e8c0 5e 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20  ^If an internal 
2e8d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
2e8e0 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75  quested that wou
2e8f0 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
2e900 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2e910 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
2e920 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
2e930 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a  invoked one or.*
2e940 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  * more times to 
2e950 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
2e960 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
2e970 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66  location is perf
2e980 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ormed..**.** ^Th
2e990 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65  e limit is calle
2e9a0 64 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  d "soft" because
2e9b0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
2e9c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
2e9d0 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75  * cannot free su
2e9e0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
2e9f0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
2ea00 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
2ea10 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
2ea20 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
2ea30 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
2ea40 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
2ea50 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
2ea60 2a 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  **.** ^A negativ
2ea70 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20  e or zero value 
2ea80 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74  for N means that
2ea90 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66   there is no sof
2eaa0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64  t heap limit and
2eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  .** [sqlite3_rel
2eac0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77  ease_memory()] w
2ead0 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ill only be call
2eae0 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ed when memory i
2eaf0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
2eb00 5e 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c  ^The default val
2eb10 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
2eb20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
2eb30 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  ro..**.** ^(SQLi
2eb40 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20  te makes a best 
2eb50 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20  effort to honor 
2eb60 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2eb70 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74  mit..** But if t
2eb80 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2eb90 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e  it cannot be hon
2eba0 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20  ored, execution 
2ebb0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65  will.** continue
2ebc0 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f   without error o
2ebd0 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29  r notification.)
2ebe0 5e 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74  ^  This is why t
2ebf0 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63  he limit is.** c
2ec00 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c  alled a "soft" l
2ec10 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76  imit.  It is adv
2ec20 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
2ec30 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
2ec40 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
2ec50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   this routine on
2ec60 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74  ly constrained t
2ec70 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
2ec80 6f 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67  ocated by a sing
2ec90 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20  le thread - the 
2eca0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2ecb0 68 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e  hich this routin
2ecc0 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69  e.** runs.  Begi
2ecd0 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74  nning with SQLit
2ece0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c  e version 3.5.0,
2ecf0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2ed00 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69  imit is.** appli
2ed10 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64  ed to all thread
2ed20 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65  s. The value spe
2ed30 63 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73  cified for the s
2ed40 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
2ed50 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f  * is an upper bo
2ed60 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c  und on the total
2ed70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2ed80 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61  on for all threa
2ed90 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f  ds. In.** versio
2eda0 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73  n 3.5.0 there is
2edb0 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f   no mechanism fo
2edc0 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68  r limiting the h
2edd0 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a  eap usage for.**
2ede0 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65   individual thre
2edf0 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ads..*/.void sql
2ee00 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
2ee10 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  imit(int);../*.*
2ee20 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72  * CAPI3REF: Extr
2ee30 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f  act Metadata Abo
2ee40 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41  ut A Column Of A
2ee50 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68   Table.**.** ^Th
2ee60 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2ee70 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75  ns metadata abou
2ee80 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c  t a specific col
2ee90 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69  umn of a specifi
2eea0 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61  c.** database ta
2eeb0 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75  ble accessible u
2eec0 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61  sing the [databa
2eed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
2eee0 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20  andle.** passed 
2eef0 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e  as the first fun
2ef00 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2ef10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d  **.** ^The colum
2ef20 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  n is identified 
2ef30 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74  by the second, t
2ef40 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2ef50 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a  parameters to.**
2ef60 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20   this function. 
2ef70 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2ef80 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
2ef90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2efa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
2efb0 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
2efc0 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  , or an attached
2efd0 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
2efe0 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
2eff0 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
2f000 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20  NULL. ^If it is 
2f010 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
2f020 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2f030 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
2f040 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
2f050 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
2f060 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79  lgorithm used by
2f070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2f080 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c  gine to.** resol
2f090 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74  ve unqualified t
2f0a0 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e  able references.
2f0b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2f0c0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
2f0d0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
2f0e0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
2f0f0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
2f100 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  n.** name of the
2f110 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
2f120 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
2f130 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
2f140 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61  parameters.** ma
2f150 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
2f160 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65   ^Metadata is re
2f170 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e  turned by writin
2f180 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20  g to the memory 
2f190 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64  locations passed
2f1a0 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61   as the 5th.** a
2f1b0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61  nd subsequent pa
2f1c0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
2f1d0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20   function. ^Any 
2f1e0 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e  of these argumen
2f1f0 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c  ts may be.** NUL
2f200 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  L, in which case
2f210 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2f220 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65  ng element of me
2f230 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65  tadata is omitte
2f240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63  d..**.** ^(<bloc
2f250 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2f260 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2f270 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65   <tr><th> Parame
2f280 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c  ter <th> Output<
2f290 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65  br>Type <th>  De
2f2a0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  scription.**.** 
2f2b0 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64  <tr><td> 5th <td
2f2c0 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2f2d0 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20  d> Data type.** 
2f2e0 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64  <tr><td> 6th <td
2f2f0 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74  > const char* <t
2f300 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75  d> Name of defau
2f310 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  lt collation seq
2f320 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  uence.** <tr><td
2f330 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 7th <td> int  
2f340 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
2f350 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61   if column has a
2f360 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
2f370 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  aint.** <tr><td>
2f380 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   8th <td> int   
2f390 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2f3a0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72  if column is par
2f3b0 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59  t of the PRIMARY
2f3c0 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   KEY.** <tr><td>
2f3d0 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   9th <td> int   
2f3e0 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
2f3f0 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55  if column is [AU
2f400 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20  TOINCREMENT].** 
2f410 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2f420 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2f430 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f  * ^The memory po
2f440 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2f450 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65  character pointe
2f460 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20  rs returned for 
2f470 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69  the.** declarati
2f480 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c  on type and coll
2f490 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
2f4a0 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74  s valid only unt
2f4b0 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63  il the next.** c
2f4c0 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74  all to any SQLit
2f4d0 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a  e API function..
2f4e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
2f4f0 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
2f500 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
2f510 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2f520 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2f530 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
2f540 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73  cified column is
2f550 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20   "rowid", "oid" 
2f560 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64  or "_rowid_" and
2f570 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20   an.** [INTEGER 
2f580 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
2f590 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
2f5a0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2f5b0 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
2f5c0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
2f5d0 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
2f5e0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
2f5f0 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66  red column. ^(If
2f600 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20   there is no.** 
2f610 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
2f620 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49  red [INTEGER PRI
2f630 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2f640 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
2f650 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
2f660 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f  are set as follo
2f670 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  ws:.**.** <pre>.
2f680 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65  **     data type
2f690 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20  : "INTEGER".**  
2f6a0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71     collation seq
2f6b0 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a  uence: "BINARY".
2f6c0 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a  **     not null:
2f6d0 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72   0.**     primar
2f6e0 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20  y key: 1.**     
2f6f0 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20  auto increment: 
2f700 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  0.** </pre>)^.**
2f710 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
2f720 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65  ion may load one
2f730 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73   or more schemas
2f740 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66   from database f
2f750 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65  iles. If an.** e
2f760 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2f770 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c  ng this process,
2f780 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65   or if the reque
2f790 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f  sted table or co
2f7a0 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62  lumn.** cannot b
2f7b0 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72  e found, an [err
2f7c0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2f7d0 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f  rned and an erro
2f7e0 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a  r message left.*
2f7f0 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * in the [databa
2f800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
2f810 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20  to be retrieved 
2f820 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72  using sqlite3_er
2f830 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a  rmsg()).)^.**.**
2f840 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e   ^This API is on
2f850 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2f860 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2f870 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2f880 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2f890 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2f8a0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2f8b0 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
2f8c0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2f8d0 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f  e3_table_column_
2f8e0 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69  metadata(.  sqli
2f8f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2f900 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65          /* Conne
2f910 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a  ction handle */.
2f920 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
2f930 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a  bName,        /*
2f940 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f   Database name o
2f950 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73  r NULL */.  cons
2f960 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61  t char *zTableNa
2f970 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65  me,     /* Table
2f980 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74   name */.  const
2f990 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61   char *zColumnNa
2f9a0 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e  me,    /* Column
2f9b0 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20   name */.  char 
2f9c0 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79  const **pzDataTy
2f9d0 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  pe,    /* OUTPUT
2f9e0 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20  : Declared data 
2f9f0 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  type */.  char c
2fa00 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71  onst **pzCollSeq
2fa10 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  ,     /* OUTPUT:
2fa20 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   Collation seque
2fa30 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e  nce name */.  in
2fa40 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20  t *pNotNull,    
2fa50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2fa60 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54  PUT: True if NOT
2fa70 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2fa80 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74   exists */.  int
2fa90 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20   *pPrimaryKey,  
2faa0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2fab0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2fac0 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f  mn part of PK */
2fad0 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63  .  int *pAutoinc
2fae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2faf0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2fb00 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f  f column is auto
2fb10 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b  -increment */.);
2fb20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fb30 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  : Load An Extens
2fb40 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ion.**.** ^This 
2fb50 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20  interface loads 
2fb60 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  an SQLite extens
2fb70 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d  ion library from
2fb80 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e   the named file.
2fb90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fba0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2fbb0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  on() interface a
2fbc0 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20  ttempts to load 
2fbd0 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74  an.** SQLite ext
2fbe0 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63  ension library c
2fbf0 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20  ontained in the 
2fc00 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a  file zFile..**.*
2fc10 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69  * ^The entry poi
2fc20 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20  nt is zProc..** 
2fc30 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c  ^zProc may be 0,
2fc40 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
2fc50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65  he name of the e
2fc60 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65  ntry point.** de
2fc70 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74  faults to "sqlit
2fc80 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69  e3_extension_ini
2fc90 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  t"..** ^The sqli
2fca0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2fcb0 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  on() interface r
2fcc0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
2fcd0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
2fce0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52   and [SQLITE_ERR
2fcf0 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67  OR] if something
2fd00 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2fd10 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
2fd20 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67  urs and pzErrMsg
2fd30 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20   is not 0, then 
2fd40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2fd50 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2fd60 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2fd70 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  l attempt to.** 
2fd80 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
2fd90 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ith error messag
2fda0 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
2fdb0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69   memory.** obtai
2fdc0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2fdd0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65  3_malloc()]. The
2fde0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2fdf0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65  n.** should free
2fe00 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20   this memory by 
2fe10 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2fe20 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2fe30 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
2fe40 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c  ng must be enabl
2fe50 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
2fe60 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
2fe70 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72  _extension()] pr
2fe80 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74  ior to calling t
2fe90 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65  his API,.** othe
2fea0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77  rwise an error w
2feb0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
2fec0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
2fed0 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73  the [load_extens
2fee0 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ion() SQL functi
2fef0 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  on]..*/.int sqli
2ff00 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2ff10 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2ff20 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c  b,          /* L
2ff30 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f  oad the extensio
2ff40 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61  n into this data
2ff50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ff60 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ff70 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61  *zFile,    /* Na
2ff80 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  me of the shared
2ff90 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2ffa0 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f  ing extension */
2ffb0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2ffc0 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72  Proc,    /* Entr
2ffd0 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65  y point.  Derive
2ffe0 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20  d from zFile if 
2fff0 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  0 */.  char **pz
30000 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20  ErrMsg       /* 
30010 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67  Put error messag
30020 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20  e here if not 0 
30030 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
30040 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
30050 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69   Disable Extensi
30060 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a  on Loading.**.**
30070 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f   ^So as not to o
30080 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c  pen security hol
30090 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c  es in older appl
300a0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72  ications that ar
300b0 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20  e.** unprepared 
300c0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74  to deal with ext
300d0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20  ension loading, 
300e0 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f  and as a means o
300f0 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65  f disabling.** e
30100 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
30110 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
30120 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  g user-entered S
30130 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  QL, the followin
30140 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76  g API.** is prov
30150 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65  ided to turn the
30160 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
30170 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68  xtension()] mech
30180 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66  anism on and off
30190 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
301a0 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66  on loading is of
301b0 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65  f by default. Se
301c0 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a  e ticket #1863..
301d0 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c  ** ^Call the sql
301e0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
301f0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75  _extension() rou
30200 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d  tine with onoff=
30210 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78  =1.** to turn ex
30220 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
30230 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77  on and call it w
30240 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20  ith onoff==0 to 
30250 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20  turn.** it back 
30260 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e  off again..*/.in
30270 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
30280 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
30290 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74  sqlite3 *db, int
302a0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
302b0 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61  CAPI3REF: Automa
302c0 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
302d0 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Extensions.**.**
302e0 20 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62   ^This API can b
302f0 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f  e invoked at pro
30300 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20  gram startup in 
30310 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65  order to registe
30320 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
30330 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b   statically link
30340 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68  ed extensions th
30350 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c  at will be avail
30360 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e  able.** to all n
30370 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
30380 6e 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a  nections]..**.**
30390 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
303a0 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72  stores a pointer
303b0 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f   to the extensio
303c0 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a  n entry point.**
303d0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61   in an array tha
303e0 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  t is obtained fr
303f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
30400 6f 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d  oc()].  That mem
30410 6f 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f  ory.** is deallo
30420 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  cated by [sqlite
30430 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
30440 65 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a  ension()].)^.**.
30450 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
30460 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65  n registers an e
30470 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70  xtension entry p
30480 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20  oint that is.** 
30490 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
304a0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
304b0 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
304c0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73  onnection].** is
304d0 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73   opened using [s
304e0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
304f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
30500 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
30510 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a  e3_open_v2()]..*
30520 2a 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74  * ^Duplicate ext
30530 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65  ensions are dete
30540 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20  cted so calling 
30550 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
30560 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77  multiple times w
30570 69 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74  ith the same ext
30580 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65  ension is harmle
30590 73 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69  ss..** ^Automati
305a0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70  c extensions app
305b0 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68  ly across all th
305c0 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  reads..*/.int sq
305d0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
305e0 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74  sion(void (*xEnt
305f0 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b  ryPoint)(void));
30600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30610 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69  : Reset Automati
30620 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  c Extension Load
30630 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  ing.**.** ^(This
30640 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
30650 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c  es all previousl
30660 79 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74  y registered aut
30670 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73  omatic.** extens
30680 69 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20  ions. It undoes 
30690 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c  the effect of al
306a0 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69  l prior.** [sqli
306b0 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
306c0 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a  on()] calls.)^.*
306d0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
306e0 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74  ion disables aut
306f0 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
30700 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73  s in all threads
30710 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
30720 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74  3_reset_auto_ext
30730 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f  ension(void);../
30740 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
30750 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
30760 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
30770 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  m is currently c
30780 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
30790 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
307a0 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
307b0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
307c0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
307d0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
307e0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
307f0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
30800 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
30810 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
30820 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
30830 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
30840 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
30850 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
30860 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
30870 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
30880 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
30890 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
308a0 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
308b0 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65  * Structures use
308c0 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
308d0 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
308e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
308f0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
30900 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79  sqlite3_vtab;.ty
30910 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
30920 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
30930 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
30940 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  fo;.typedef stru
30950 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
30960 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76  cursor sqlite3_v
30970 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65  tab_cursor;.type
30980 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30990 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65  e3_module sqlite
309a0 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a  3_module;../*.**
309b0 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
309c0 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a  al Table Object.
309d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
309e0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72  ite3_module {vir
309f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
30a00 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74  e}.**.** This st
30a10 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d  ructure, sometim
30a20 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76  es called a a "v
30a30 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30a40 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65  ule", .** define
30a50 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  s the implementa
30a60 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75  tion of a [virtu
30a70 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a  al tables].  .**
30a80 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
30a90 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20  consists mostly 
30aa0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
30ab0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
30ac0 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c   ^A virtual tabl
30ad0 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61  e module is crea
30ae0 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69  ted by filling i
30af0 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  n a persistent.*
30b00 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
30b10 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  is structure and
30b20 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74   passing a point
30b30 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61  er to that insta
30b40 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nce.** to [sqlit
30b50 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
30b60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30b70 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
30b80 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67  ()]..** ^The reg
30b90 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
30ba0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
30bb0 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
30bc0 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
30bd0 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
30be0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30bf0 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
30c00 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
30c10 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
30c20 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
30c30 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
30c40 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
30c50 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
30c60 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
30c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
30c80 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
30c90 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
30ca0 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
30cb0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
30cc0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
30cd0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
30ce0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
30cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
30d00 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
30d10 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
30d20 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
30d30 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
30d40 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
30d50 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
30d60 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
30d70 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
30d80 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
30d90 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
30da0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
30db0 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
30dc0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
30dd0 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
30de0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
30df0 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
30e00 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30e10 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
30e20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30e30 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30e40 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
30e50 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
30e60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
30e70 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
30e80 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
30e90 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30ea0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
30eb0 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
30ec0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
30ed0 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
30ee0 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
30ef0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
30f00 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
30f10 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
30f20 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
30f30 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
30f40 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
30f50 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30f60 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
30f70 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
30f80 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
30f90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30fa0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
30fb0 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
30fc0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
30fd0 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
30fe0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
30ff0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
31000 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
31010 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
31020 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
31030 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
31040 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
31050 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
31060 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31070 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
31080 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
31090 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
310a0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
310b0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
310c0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
310d0 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
310e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
310f0 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
31100 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
31110 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31120 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
31130 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
31140 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31150 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31160 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31170 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
31180 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
31190 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
311a0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
311b0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
311c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
311d0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
311e0 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
311f0 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  tion.** KEYWORDS
31200 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  : sqlite3_index_
31210 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  info.**.** The s
31220 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
31230 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  o structure and 
31240 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65  its substructure
31250 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20  s is used to.** 
31260 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
31270 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
31280 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
31290 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   the [xBestIndex
312a0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  ].** method of a
312b0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
312c0 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69  module].  The fi
312d0 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
312e0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
312f0 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
31300 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
31310 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
31320 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
31330 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
31340 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
31350 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e   fields..**.** ^
31360 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  (The aConstraint
31370 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
31380 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
31390 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
313a0 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72   form:.**.** <pr
313b0 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
313c0 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  </pre>.**.** whe
313d0 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
313e0 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
313f0 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68  r &gt;=.)^  ^(Th
31400 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65  e particular ope
31410 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72  rator is.** stor
31420 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  ed in aConstrain
31430 74 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65  t[].op.)^  ^(The
31440 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
31450 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
31460 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74  n.** aConstraint
31470 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e  [].iColumn.)^  ^
31480 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75  (aConstraint[].u
31490 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
314a0 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
314b0 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
314c0 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
314d0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
314e0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
314f0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
31500 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
31510 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ot.)^.**.** ^The
31520 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d   optimizer autom
31530 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73  atically inverts
31540 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f   terms of the fo
31550 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75  rm "expr OP colu
31560 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73  mn".** and makes
31570 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63   other simplific
31580 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48  ations to the WH
31590 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e  ERE clause in an
315a0 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67   attempt to.** g
315b0 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45  et as many WHERE
315c0 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
315d0 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77  to the form show
315e0 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69  n above as possi
315f0 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f  ble..** ^The aCo
31600 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
31610 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
31620 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
31630 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c   that are.** rel
31640 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72  evant to the par
31650 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
31660 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
31670 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f  ied..**.** ^Info
31680 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
31690 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
316a0 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
316b0 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45  OrderBy[]..** ^E
316c0 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
316d0 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
316e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
316f0 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
31700 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e  .** The [xBestIn
31710 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74  dex] method must
31720 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
31730 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
31740 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
31750 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
31760 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
31770 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76  ilter.  ^If argv
31780 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20  Index>0 then.** 
31790 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
317a0 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65  ide of the corre
317b0 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72  sponding aConstr
317c0 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61  aint[] is evalua
317d0 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d  ted.** and becom
317e0 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78  es the argvIndex
317f0 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67  -th entry in arg
31800 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72  v.  ^(If aConstr
31810 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
31820 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
31830 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
31840 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
31850 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
31860 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
31870 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
31880 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
31890 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a   by SQLite.)^.**
318a0 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20  .** ^The idxNum 
318b0 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
318c0 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
318d0 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nd passed into t
318e0 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20  he.** [xFilter] 
318f0 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c  method..** ^[sql
31900 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
31910 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78  used to free idx
31920 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  Ptr if and only 
31930 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65  if.** needToFree
31940 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a  IdxPtr is true..
31950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72  **.** ^The order
31960 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73  ByConsumed means
31970 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f   that output fro
31980 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65  m [xFilter]/[xNe
31990 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  xt] will occur i
319a0 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
319b0 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
319c0 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
319d0 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
319e0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
319f0 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
31a00 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
31a10 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
31a20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
31a30 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
31a40 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
31a50 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
31a60 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
31a70 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
31a80 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
31a90 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
31aa0 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
31ab0 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
31ac0 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
31ad0 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
31ae0 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
31af0 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
31b00 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
31b10 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
31b20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
31b30 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
31b40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
31b50 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
31b60 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
31b70 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
31b80 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
31b90 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
31ba0 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
31bb0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
31bc0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
31bd0 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
31be0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
31bf0 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
31c00 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
31c10 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
31c20 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
31c30 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
31c40 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
31c50 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
31c60 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
31c70 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
31c80 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
31c90 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
31ca0 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
31cb0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
31cc0 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
31cd0 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
31ce0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
31cf0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
31d00 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
31d10 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
31d20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
31d30 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
31d40 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
31d50 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
31d60 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
31d70 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
31d80 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
31d90 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
31da0 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
31db0 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
31dc0 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
31dd0 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
31de0 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
31df0 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
31e00 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
31e10 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
31e20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
31e30 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
31e40 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
31e50 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
31e60 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
31e70 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
31e80 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
31e90 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
31ea0 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
31eb0 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
31ec0 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
31ed0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
31ee0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
31ef0 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20  intUsage;.  int 
31f00 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20  idxNum;         
31f10 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
31f20 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66   used to identif
31f30 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20  y the index */. 
31f40 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20   char *idxStr;  
31f50 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
31f60 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20  tring, possibly 
31f70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
31f80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a  lite3_malloc */.
31f90 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
31fa0 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20  IdxStr;      /* 
31fb0 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e  Free idxStr usin
31fc0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
31fd0 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e   if true */.  in
31fe0 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  t orderByConsume
31ff0 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  d;       /* True
32000 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c   if output is al
32010 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f  ready ordered */
32020 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61  .  double estima
32030 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a  tedCost;      /*
32040 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20   Estimated cost 
32050 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e  of using this in
32060 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e  dex */.};.#defin
32070 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
32080 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20  ONSTRAINT_EQ    
32090 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
320a0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
320b0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e  T_GT    4.#defin
320c0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
320d0 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
320e0 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
320f0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
32100 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69  T_LT    16.#defi
32110 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
32120 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20  CONSTRAINT_GE   
32130 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
32140 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32150 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a  INT_MATCH 64../*
32160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
32170 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
32180 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
32190 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ation.**.** ^The
321a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
321b0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
321c0 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20   a new [virtual 
321d0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61  table module] na
321e0 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e  me..** ^Module n
321f0 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
32200 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a  istered before.*
32210 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77  * creating a new
32220 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
32230 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c   using the modul
32240 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69  e and before usi
32250 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74  ng a.** preexist
32260 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ing [virtual tab
32270 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  le] for the modu
32280 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  le..**.** ^The m
32290 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65  odule name is re
322a0 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20  gistered on the 
322b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
322c0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a  tion] specified.
322d0 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
322e0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
322f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   name of the mod
32300 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ule is given by 
32310 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70  the .** second p
32320 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
32330 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
32340 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
32350 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
32360 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69  ation of the [vi
32370 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32380 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72  le].   ^The four
32390 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
323a0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
323b0 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
323c0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
323d0 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e  ed through.** in
323e0 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d  to the [xCreate]
323f0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
32400 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76  methods of the v
32410 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
32420 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65  ule.** when a ne
32430 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
32440 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61  is be being crea
32450 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c  ted or reinitial
32460 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ized..**.** ^The
32470 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32480 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65  module_v2() inte
32490 72 66 61 63 65 20 68 61 73 20 61 20 66 69 66 74  rface has a fift
324a0 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  h parameter whic
324b0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
324c0 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f  r to a destructo
324d0 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e  r for the pClien
324e0 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20  tData.  ^SQLite 
324f0 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  will.** invoke t
32500 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
32510 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73  nction (if it is
32520 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20   not NULL) when 
32530 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e  SQLite.** no lon
32540 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43  ger needs the pC
32550 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65  lientData pointe
32560 72 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  r.  ^The sqlite3
32570 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
32580 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
32590 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
325a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
325b0 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61  dule_v2() with a
325c0 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63   NULL.** destruc
325d0 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tor..*/.int sqli
325e0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
325f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
32600 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
32610 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
32620 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
32630 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
32640 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
32650 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
32660 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
32670 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
32680 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
32690 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
326a0 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
326b0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
326c0 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ata          /* 
326d0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
326e0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
326f0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
32700 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32710 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
32720 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
32730 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
32740 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
32750 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
32760 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
32770 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
32780 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
32790 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
327a0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
327b0 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
327c0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
327d0 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
327e0 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f  tData,         /
327f0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
32800 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
32810 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
32820 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
32830 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
32840 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
32850 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
32860 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
32870 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
32880 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
32890 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
328a0 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
328b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
328c0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
328d0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
328e0 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a  s.** of this obj
328f0 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20  ect to describe 
32900 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
32910 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20  tance.** of the 
32920 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
32930 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
32940 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f  will.** be tailo
32950 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
32960 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
32970 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
32980 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70  tation..** The p
32990 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
329a0 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
329b0 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
329c0 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a  ields that are.*
329d0 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  * common to all 
329e0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
329f0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56  ations..**.** ^V
32a00 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
32a10 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
32a20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
32a30 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
32a40 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
32a50 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
32a60 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72  printf()] to zEr
32a70 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
32a80 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
32a90 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
32aa0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
32ab0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
32ac0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
32ad0 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61  )].** prior to a
32ae0 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73  ssigning a new s
32af0 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67  tring to zErrMsg
32b00 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72  .  ^After the er
32b10 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
32b20 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
32b30 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
32b40 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
32b50 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
32b60 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
32b70 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
32b80 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
32b90 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
32ba0 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73   be zeroed..*/.s
32bb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
32bc0 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
32bd0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
32be0 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
32bf0 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
32c00 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
32c10 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
32c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32c30 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53   /* NO LONGER US
32c40 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ED */.  char *zE
32c50 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
32c60 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
32c70 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
32c80 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
32c90 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
32ca0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
32cb0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
32cc0 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
32cd0 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
32ce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32cf0 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
32d00 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a  Cursor Object.**
32d10 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
32d20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
32d30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
32d40 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72  rsor}.**.** Ever
32d50 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
32d60 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
32d70 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
32d80 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
32d90 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  * following stru
32da0 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
32db0 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
32dc0 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  oint into the.**
32dd0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
32de0 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
32df0 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
32e00 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
32e10 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
32e20 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
32e30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
32e40 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f  odule.xOpen | xO
32e50 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  pen] method of t
32e60 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72  he module and ar
32e70 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62  e destroyed.** b
32e80 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  y the [sqlite3_m
32e90 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78  odule.xClose | x
32ea0 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20  Close] method.  
32eb0 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64  Cursors are used
32ec0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c  .** by the [xFil
32ed0 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b  ter], [xNext], [
32ee0 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d  xEof], [xColumn]
32ef0 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d  , and [xRowid] m
32f00 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65  ethods.** of the
32f10 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
32f20 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
32f30 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
32f40 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
32f50 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
32f60 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
32f70 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
32f80 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
32f90 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
32fa0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
32fb0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
32fc0 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
32fd0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
32fe0 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
32ff0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
33000 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
33010 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
33020 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
33030 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
33040 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
33050 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
33060 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
33070 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
33080 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
33090 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
330a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
330b0 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
330c0 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
330d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72  .**.** ^The [xCr
330e0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
330f0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
33100 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  a.** [virtual ta
33110 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c  ble module] call
33120 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a   this interface.
33130 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
33140 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
33150 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
33160 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
33170 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
33180 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
33190 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
331a0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
331b0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
331c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51   const char *zSQ
331d0 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  L);../*.** CAPI3
331e0 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20  REF: Overload A 
331f0 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56  Function For A V
33200 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
33210 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62  ** ^(Virtual tab
33220 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
33230 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
33240 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
33250 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
33260 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63  g the [xFindFunc
33270 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  tion] method of 
33280 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
33290 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a  le module].  .**
332a0 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
332b0 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
332c0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
332d0 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
332e0 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
332f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
33300 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
33310 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
33320 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
33330 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
33340 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
33350 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
33360 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
33370 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
33380 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
33390 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
333a0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
333b0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20  n is created.)^ 
333c0 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
333d0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
333e0 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
333f0 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
33400 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
33410 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
33420 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
33430 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
33440 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
33450 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
33460 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
33470 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
33480 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
33490 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
334a0 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  by a [virtual ta
334b0 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ble]..*/.int sql
334c0 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75  ite3_overload_fu
334d0 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c  nction(sqlite3*,
334e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
334f0 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67  ncName, int nArg
33500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
33510 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
33520 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
33530 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61  hanism defined a
33540 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a  bove (back up.**
33550 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65   to a comment re
33560 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72  markably similar
33570 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73   to this one) is
33580 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
33590 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
335a0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
335b0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
335c0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
335d0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
335e0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
335f0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
33600 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
33610 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
33620 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
33630 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
33640 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
33650 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
33660 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
33670 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
33680 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
33690 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
336a0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
336b0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt..*/../*.** CA
336c0 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
336d0 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
336e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42  .** KEYWORDS: {B
336f0 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f  LOB handle} {BLO
33700 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a  B handles}.**.**
33710 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
33720 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
33730 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42  esents an open B
33740 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  LOB on which.** 
33750 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
33760 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
33770 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62   BLOB I/O] can b
33780 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20  e performed..** 
33790 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73  ^Objects of this
337a0 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65   type are create
337b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
337c0 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  ob_open()].** an
337d0 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
337e0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
337f0 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b  se()]..** ^The [
33800 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33810 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
33820 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
33830 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
33840 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
33850 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
33860 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
33870 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68  the BLOB..** ^Th
33880 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
33890 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
338a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
338b0 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
338c0 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
338d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
338e0 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
338f0 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
33900 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
33910 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
33920 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28  tal I/O.**.** ^(
33930 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20  This interfaces 
33940 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61  opens a [BLOB ha
33950 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74  ndle | handle] t
33960 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74  o the BLOB locat
33970 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f  ed.** in row iRo
33980 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d  w, column zColum
33990 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20  n, table zTable 
339a0 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b  in database zDb;
339b0 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  .** in other wor
339c0 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f  ds, the same BLO
339d0 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20  B that would be 
339e0 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
339f0 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
33a00 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
33a10 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
33a20 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69  HERE [rowid] = i
33a30 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  Row;.** </pre>)^
33a40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
33a50 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
33a60 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
33a70 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
33a80 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20  ned for read.** 
33a90 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
33aa0 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f  . ^If it is zero
33ab0 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  , the BLOB is op
33ac0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63  ened for read ac
33ad0 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  cess..** ^It is 
33ae0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
33af0 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
33b00 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e  at is part of an
33b10 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72   index or primar
33b20 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72  y .** key for wr
33b30 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65  iting. ^If [fore
33b40 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
33b50 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  nts] are enabled
33b60 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20  , it is .** not 
33b70 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
33b80 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
33b90 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69  s part of a [chi
33ba0 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74  ld key] for writ
33bb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ing..**.** ^Note
33bc0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
33bd0 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74  se name is not t
33be0 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74  he filename that
33bf0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
33c00 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61   database but ra
33c10 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69  ther the symboli
33c20 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  c name of the da
33c30 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61  tabase that.** a
33c40 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65  ppears after the
33c50 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e   AS keyword when
33c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
33c70 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67   connected using
33c80 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46   [ATTACH]..** ^F
33c90 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
33ca0 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
33cb0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
33cc0 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20  "main"..** ^For 
33cd0 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
33ce0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
33cf0 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
33d00 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  ^(On success, [S
33d10 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
33d20 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
33d30 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  w [BLOB handle] 
33d40 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  is written.** to
33d50 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77   *ppBlob. Otherw
33d60 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
33d70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
33d80 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73  and *ppBlob is s
33d90 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75  et.** to be a nu
33da0 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a  ll pointer.)^.**
33db0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
33dc0 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
33dd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
33de0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
33df0 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
33e00 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
33e10 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
33e20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
33e30 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
33e40 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f  * functions. ^No
33e50 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
33e60 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
33e70 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
33e80 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
33e90 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
33ea0 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
33eb0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33ec0 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
33ed0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
33ee0 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
33ef0 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
33f00 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  utine..**.** ^(I
33f10 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61  f the row that a
33f20 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69   BLOB handle poi
33f30 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69  nts to is modifi
33f40 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44  ed by an.** [UPD
33f50 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20  ATE], [DELETE], 
33f60 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49  or by [ON CONFLI
33f70 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73  CT] side-effects
33f80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  .** then the BLO
33f90 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b  B handle is mark
33fa0 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e  ed as "expired".
33fb0 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65  .** This is true
33fc0 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f   if any column o
33fd0 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61  f the row is cha
33fe0 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c  nged, even a col
33ff0 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  umn.** other tha
34000 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c  n the one the BL
34010 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65  OB handle is ope
34020 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c  n on.)^.** ^Call
34030 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  s to [sqlite3_bl
34040 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
34050 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
34060 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65  te()] for.** a e
34070 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64  xpired BLOB hand
34080 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  le fail with an 
34090 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
340a0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
340b0 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74  * ^(Changes writ
340c0 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ten into a BLOB 
340d0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f  prior to the BLO
340e0 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e  B expiring are n
340f0 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  ot.** rolled bac
34100 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
34110 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
34120 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
34130 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
34140 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
34150 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
34160 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
34170 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73  ion.)^.**.** ^Us
34180 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  e the [sqlite3_b
34190 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
341a0 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d  erface to determ
341b0 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  ine the size of.
341c0 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c  ** the opened bl
341d0 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f  ob.  ^The size o
341e0 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74  f a blob may not
341f0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74   be changed by t
34200 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
34210 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41  .  Use the [UPDA
34220 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  TE] SQL command 
34230 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69  to change the si
34240 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e  ze of a.** blob.
34250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
34260 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
34270 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ob()] and [sqlit
34280 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
34290 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ob()] interfaces
342a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c  .** and the buil
342b0 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20  t-in [zeroblob] 
342c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  SQL function can
342d0 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73   be used, if des
342e0 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61  ired,.** to crea
342f0 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72  te an empty, zer
34300 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e  o-filled blob in
34310 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f   which to read o
34320 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a  r write using.**
34330 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34340 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
34350 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c  a resource leak,
34360 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f   every open [BLO
34370 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64  B handle] should
34380 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62   eventually.** b
34390 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20  e released by a 
343a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
343b0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
343c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
343d0 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
343e0 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
343f0 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
34400 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
34410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
34420 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
34430 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
34440 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
34450 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
34460 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34470 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f  REF: Close A BLO
34480 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e  B Handle.**.** ^
34490 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b  Closes an open [
344a0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a  BLOB handle]..**
344b0 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42  .** ^Closing a B
344c0 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20  LOB shall cause 
344d0 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e  the current tran
344e0 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69  saction to commi
344f0 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72  t.** if there ar
34500 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73  e no other BLOBs
34510 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65  , no pending pre
34520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
34530 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74  , and the.** dat
34540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34550 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d   is in [autocomm
34560 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66  it mode]..** ^If
34570 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65   any writes were
34580 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f   made to the BLO
34590 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65  B, they might be
345a0 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a   held in cache.*
345b0 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73  * until the clos
345c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74  e operation if t
345d0 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a  hey will fit..**
345e0 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68  .** ^(Closing th
345f0 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72  e BLOB often for
34600 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a  ces the changes.
34610 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61  ** out to disk a
34620 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f  nd so if any I/O
34630 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74   errors occur, t
34640 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  hey will likely 
34650 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20  occur.** at the 
34660 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c  time when the BL
34670 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41  OB is closed.  A
34680 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  ny errors that o
34690 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63  ccur during.** c
346a0 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72  losing are repor
346b0 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72  ted as a non-zer
346c0 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29  o return value.)
346d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c  ^.**.** ^(The BL
346e0 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63  OB is closed unc
346f0 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45  onditionally.  E
34700 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74  ven if this rout
34710 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ine returns.** a
34720 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68  n error code, th
34730 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20  e BLOB is still 
34740 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  closed.)^.**.** 
34750 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
34760 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c  utine with a nul
34770 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20  l pointer (such 
34780 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  as would be retu
34790 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69  rned.** by a fai
347a0 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  led call to [sql
347b0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
347c0 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  ]) is a harmless
347d0 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73   no-op..*/.int s
347e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
347f0 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
34800 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34810 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53  EF: Return The S
34820 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
34830 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  LOB.**.** ^Retur
34840 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62  ns the size in b
34850 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
34860 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
34870 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66  the .** successf
34880 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f  ully opened [BLO
34890 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73  B handle] in its
348a0 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
348b0 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65   ^The.** increme
348c0 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f  ntal blob I/O ro
348d0 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20  utines can only 
348e0 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74  read or overwrit
348f0 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  ing existing.** 
34900 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68  blob content; th
34910 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  ey cannot change
34920 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
34930 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lob..**.** This 
34940 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
34950 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
34960 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
34970 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
34980 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
34990 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
349a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
349b0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
349c0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
349d0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
349e0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
349f0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
34a00 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
34a10 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
34a20 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
34a30 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
34a40 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
34a50 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  ehavior..*/.int 
34a60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
34a70 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
34a80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
34a90 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46  REF: Read Data F
34aa0 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
34ab0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e  mentally.**.** ^
34ac0 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  (This function i
34ad0 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
34ae0 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
34af0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
34b00 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  nto a.** caller-
34b10 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
34b20 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
34b30 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
34b40 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f   buffer Z.** fro
34b50 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  m the open BLOB,
34b60 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
34b70 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a  set iOffset.)^.*
34b80 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20  *.** ^If offset 
34b90 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
34ba0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
34bb0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
34bc0 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
34bd0 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
34be0 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
34bf0 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e   is read.  ^If N
34c00 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
34c10 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
34c20 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
34c30 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34c40 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
34c50 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f  ..** ^The size o
34c60 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20  f the blob (and 
34c70 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75  hence the maximu
34c80 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66  m value of N+iOf
34c90 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20  fset).** can be 
34ca0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
34cb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
34cc0 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
34cd0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  rface..**.** ^An
34ce0 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
34cf0 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64   from an expired
34d00 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
34d10 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
34d20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
34d30 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34d40 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
34d50 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  , sqlite3_blob_r
34d60 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
34d70 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65  LITE_OK..** Othe
34d80 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72  rwise, an [error
34d90 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
34da0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
34db0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
34dc0 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
34dd0 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
34de0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
34df0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
34e00 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
34e10 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
34e20 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
34e30 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34e40 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
34e50 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
34e60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
34e70 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
34e80 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
34e90 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
34ea0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34eb0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34ec0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
34ed0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
34ee0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
34ef0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
34f00 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f  lob_write()]..*/
34f10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
34f20 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
34f30 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
34f40 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
34f50 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
34f60 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
34f70 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
34f80 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
34f90 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
34fa0 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
34fb0 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
34fc0 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
34fd0 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65   from a.** calle
34fe0 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
34ff0 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64  r. ^N bytes of d
35000 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
35010 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
35020 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
35030 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
35040 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
35050 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  et..**.** ^If th
35060 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
35070 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
35080 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73  rst argument was
35090 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a   not opened for.
350a0 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  ** writing (the 
350b0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
350c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
350d0 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72  _open()] was zer
350e0 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  o),.** this func
350f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
35100 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
35110 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
35120 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f  tion may only mo
35130 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  dify the content
35140 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69  s of the BLOB; i
35150 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
35160 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65  ible to increase
35170 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42   the size of a B
35180 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41  LOB using this A
35190 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  PI..** ^If offse
351a0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
351b0 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
351c0 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
351d0 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
351e0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
351f0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
35200 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20  ta is written.  
35210 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73  ^If N is.** less
35220 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49   than zero [SQLI
35230 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
35240 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
35250 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a  a is written..**
35260 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
35270 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65   BLOB (and hence
35280 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
35290 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
352a0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
352b0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
352c0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
352d0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
352e0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65  ..**.** ^An atte
352f0 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20  mpt to write to 
35300 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
35310 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
35320 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
35330 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
35340 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73  ABORT].  ^Writes
35350 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61   to the BLOB tha
35360 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65  t occurred.** be
35370 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68  fore the [BLOB h
35380 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61  andle] expired a
35390 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61  re not rolled ba
353a0 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70  ck by the.** exp
353b0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68  iration of the h
353c0 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66  andle, though of
353d0 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68   course those ch
353e0 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68  anges might.** h
353f0 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69  ave been overwri
35400 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74  tten by the stat
35410 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72  ement that expir
35420 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ed the BLOB hand
35430 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65  le.** or by othe
35440 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74  r independent st
35450 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
35460 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
35470 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
35480 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
35490 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
354a0 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63  se, an  [error c
354b0 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65  ode] or an [exte
354c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
354d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
354e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
354f0 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
35500 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
35510 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
35520 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
35530 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
35540 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35550 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
35560 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
35570 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
35580 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
35590 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
355a0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
355b0 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
355c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
355d0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
355e0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
355f0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
35600 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
35610 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
35620 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e  b_read()]..*/.in
35630 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
35640 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
35650 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
35660 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
35670 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
35680 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
35690 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
356a0 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69  jects.**.** A vi
356b0 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d  rtual filesystem
356c0 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71   (VFS) is an [sq
356d0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
356e0 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  t.** that SQLite
356f0 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63   uses to interac
35700 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e  t.** with the un
35710 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
35720 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74  ng system.  Most
35730 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63   SQLite builds c
35740 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69  ome with a.** si
35750 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53  ngle default VFS
35760 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72   that is appropr
35770 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73  iate for the hos
35780 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e  t computer..** N
35790 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ew VFSes can be 
357a0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65  registered and e
357b0 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61  xisting VFSes ca
357c0 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65  n be unregistere
357d0 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  d..** The follow
357e0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61  ing interfaces a
357f0 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a  re provided..**.
35800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35810 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72  vfs_find() inter
35820 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
35830 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20  ointer to a VFS 
35840 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a  given its name..
35850 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61  ** ^Names are ca
35860 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a  se sensitive..**
35870 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f   ^Names are zero
35880 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
35890 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49  8 strings..** ^I
358a0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61  f there is no ma
358b0 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  tch, a NULL poin
358c0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
358d0 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65  .** ^If zVfsName
358e0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
358f0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35900 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
35910 20 5e 4e 65 77 20 56 46 53 65 73 20 61 72 65 20   ^New VFSes are 
35920 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
35930 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
35940 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68  ster()..** ^Each
35950 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73   new VFS becomes
35960 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
35970 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74   if the makeDflt
35980 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a   flag is set..**
35990 20 5e 54 68 65 20 73 61 6d 65 20 56 46 53 20 63   ^The same VFS c
359a0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
359b0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
359c0 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a  without injury..
359d0 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65  ** ^To make an e
359e0 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f  xisting VFS into
359f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
35a00 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67  , register it ag
35a10 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ain.** with the 
35a20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65  makeDflt flag se
35a30 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65  t.  If two diffe
35a40 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20  rent VFSes with 
35a50 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65  the.** same name
35a60 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c   are registered,
35a70 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
35a80 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20   undefined.  If 
35a90 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69  a.** VFS is regi
35aa0 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61  stered with a na
35ab0 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20  me that is NULL 
35ac0 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
35ad0 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ng,.** then the 
35ae0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
35af0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e  fined..**.** ^Un
35b00 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
35b10 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
35b20 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
35b30 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e   interface..** ^
35b40 28 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20  (If the default 
35b50 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65  VFS is unregiste
35b60 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53  red, another VFS
35b70 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a   is chosen as.**
35b80 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54   the default.  T
35b90 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  he choice for th
35ba0 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62  e new VFS is arb
35bb0 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c  itrary.)^.*/.sql
35bc0 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65  ite3_vfs *sqlite
35bd0 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74  3_vfs_find(const
35be0 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29   char *zVfsName)
35bf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
35c00 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  s_register(sqlit
35c10 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b  e3_vfs*, int mak
35c20 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69  eDflt);.int sqli
35c30 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
35c40 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29  er(sqlite3_vfs*)
35c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35c60 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a  F: Mutexes.**.**
35c70 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
35c80 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
35c90 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a  ines for thread.
35ca0 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69  ** synchronizati
35cb0 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20  on. Though they 
35cc0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
35cd0 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
35ce0 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
35cf0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
35d00 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
35d10 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
35d20 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
35d30 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
35d40 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
35d50 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
35d60 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35d70 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68  tations.** of th
35d80 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
35d90 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69  es.  An appropri
35da0 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ate implementati
35db0 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65  on.** is selecte
35dc0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
35dd0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
35de0 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
35df0 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  g.** implementat
35e00 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
35e10 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  le in the SQLite
35e20 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   core:.**.** <ul
35e30 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  >.** <li>   SQLI
35e40 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20  TE_MUTEX_OS2.** 
35e50 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
35e60 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c  TEX_PTHREAD.** <
35e70 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
35e80 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_W32.** <li>  
35e90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
35ea0 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  OP.** </ul>)^.**
35eb0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
35ec0 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65  MUTEX_NOOP imple
35ed0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73  mentation is a s
35ee0 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a  et of routines.*
35ef0 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72  * that does no r
35f00 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20  eal locking and 
35f10 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
35f20 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73  or use in.** a s
35f30 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
35f40 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68  pplication.  ^Th
35f50 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f  e SQLITE_MUTEX_O
35f60 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  S2,.** SQLITE_MU
35f70 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64  TEX_PTHREAD, and
35f80 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
35f90 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  2 implementation
35fa0 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72  s.** are appropr
35fb0 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20  iate for use on 
35fc0 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20  OS/2, Unix, and 
35fd0 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e  Windows..**.** ^
35fe0 28 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  (If SQLite is co
35ff0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
36000 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
36010 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72  DEF preprocessor
36020 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  .** macro define
36030 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54  d (with "-DSQLIT
36040 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31  E_MUTEX_APPDEF=1
36050 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65  "), then no mute
36060 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
36070 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20  ion is included 
36080 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
36090 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74  . In this case t
360a0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
360b0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
360c0 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70  custom mutex imp
360d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e  lementation usin
360e0 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
360f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f  _CONFIG_MUTEX] o
36100 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c  ption of the sql
36110 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75  ite3_config() fu
36120 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65  nction.** before
36130 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
36140 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72  _initialize() or
36150 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69   any other publi
36160 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75  c sqlite3_.** fu
36170 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c  nction that call
36180 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
36190 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  lize().)^.**.** 
361a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
361b0 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
361c0 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
361d0 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
361e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
361f0 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20  r to it. ^If it 
36200 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
36210 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
36220 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
36230 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
36240 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c   ^SQLite.** will
36250 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
36260 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
36270 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72  error.  ^(The ar
36280 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
36290 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
362a0 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  () is one of the
362b0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
362c0 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ants:.**.** <ul>
362d0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
362e0 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c  _MUTEX_FAST.** <
362f0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36300 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c  X_RECURSIVE.** <
36310 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36320 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a  X_STATIC_MASTER.
36330 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
36340 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
36350 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
36360 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
36370 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  M2.** <li>  SQLI
36380 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36390 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  PRNG.** <li>  SQ
363a0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
363b0 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_LRU.** <li>  S
363c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
363d0 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e  IC_LRU2.** </ul>
363e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )^.**.** ^The fi
363f0 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
36400 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
36410 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f  FAST and SQLITE_
36420 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
36430 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65  .** cause sqlite
36440 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
36450 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e  to create.** a n
36460 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20  ew mutex.  ^The 
36470 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63  new mutex is rec
36480 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49  ursive when SQLI
36490 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
364a0 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75  VE.** is used bu
364b0 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c  t not necessaril
364c0 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45  y so when SQLITE
364d0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75  _MUTEX_FAST is u
364e0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65  sed..** The mute
364f0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
36500 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
36510 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
36520 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
36530 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36540 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
36550 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
36560 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
36570 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65  ant to.  ^SQLite
36580 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
36590 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
365a0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
365b0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
365c0 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66   needs one.  ^If
365d0 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
365e0 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
365f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36600 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
36610 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
36620 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
36630 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
36640 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
36650 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
36660 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
36670 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  FAST..**.** ^The
36680 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70   other allowed p
36690 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c  arameters to sql
366a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
366b0 28 29 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68  () (anything oth
366c0 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54  er.** than SQLIT
366d0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64  E_MUTEX_FAST and
366e0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
366f0 43 55 52 53 49 56 45 29 20 65 61 63 68 20 72 65  CURSIVE) each re
36700 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
36710 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
36720 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
36730 20 20 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75    ^Six static mu
36740 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
36750 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
36760 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
36770 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
36780 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
36790 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
367a0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
367b0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
367c0 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
367d0 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
367e0 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
367f0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
36800 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
36810 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
36820 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
36830 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
36840 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
36850 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
36860 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
36870 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  SIVE..**.** ^Not
36880 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
36890 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
368a0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
368b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
368c0 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
368d0 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
368e0 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
368f0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36900 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
36910 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
36920 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e  n every call.  ^
36930 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74  But for the stat
36940 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65  ic.** mutex type
36950 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65  s, the same mute
36960 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e  x is returned on
36970 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74   every call that
36980 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65   has.** the same
36990 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a   type number..**
369a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
369b0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
369c0 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
369d0 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
369e0 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
369f0 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c  mic mutex.  ^SQL
36a00 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74  ite is careful t
36a10 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65  o deallocate eve
36a20 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75  ry.** dynamic mu
36a30 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  tex that it allo
36a40 63 61 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61  cates.  The dyna
36a50 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
36a60 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73   not be in.** us
36a70 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
36a80 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74  deallocated.  At
36a90 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c  tempting to deal
36aa0 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a  locate a static.
36ab0 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73  ** mutex results
36ac0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
36ad0 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65  havior.  ^SQLite
36ae0 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74   never deallocat
36af0 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d  es.** a static m
36b00 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  utex..**.** ^The
36b10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
36b20 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74  nter() and sqlit
36b30 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72  e3_mutex_try() r
36b40 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a  outines attempt.
36b50 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75  ** to enter a mu
36b60 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65  tex.  ^If anothe
36b70 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65  r thread is alre
36b80 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d  ady within the m
36b90 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  utex,.** sqlite3
36ba0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77  _mutex_enter() w
36bb0 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71  ill block and sq
36bc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36bd0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
36be0 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e   SQLITE_BUSY.  ^
36bf0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
36c00 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63  x_try() interfac
36c10 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
36c20 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75  E_OK].** upon su
36c30 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
36c40 20 5e 28 4d 75 74 65 78 65 73 20 63 72 65 61 74   ^(Mutexes creat
36c50 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ed using.** SQLI
36c60 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
36c70 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65  VE can be entere
36c80 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
36c90 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
36ca0 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20  ead..** In such 
36cb0 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75  cases the,.** mu
36cc0 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74  tex must be exit
36cd0 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62  ed an equal numb
36ce0 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f  er of times befo
36cf0 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  re another threa
36d00 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29  d.** can enter.)
36d10 5e 20 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65  ^  ^(If the same
36d20 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
36d30 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
36d40 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65  .** kind of mute
36d50 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  x more than once
36d60 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
36d70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
36d80 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
36d90 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
36da0 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
36db0 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
36dc0 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  exes.)^.**.** ^(
36dd0 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f  Some systems (fo
36de0 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f  r example, Windo
36df0 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75  ws 95) do not su
36e00 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74  pport the operat
36e10 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
36e20 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75  ed by sqlite3_mu
36e30 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74  tex_try().  On t
36e40 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71  hose systems, sq
36e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36e60 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  ).** will always
36e70 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
36e80 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65  USY.  The SQLite
36e90 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20   core only ever 
36ea0 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  uses.** sqlite3_
36eb0 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61  mutex_try() as a
36ec0 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73  n optimization s
36ed0 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74  o this is accept
36ee0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e  able behavior.)^
36ef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36f00 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36f10 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20  ) routine exits 
36f20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73  a mutex that was
36f30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65  .** previously e
36f40 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61  ntered by the sa
36f50 6d 65 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54  me thread.   ^(T
36f60 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
36f70 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74  s undefined if t
36f80 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20  he mutex is not 
36f90 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
36fa0 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  d by the.** call
36fb0 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73  ing thread or is
36fc0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61   not currently a
36fd0 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74  llocated.  SQLit
36fe0 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20  e will.** never 
36ff0 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a  do either.)^.**.
37000 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
37010 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
37020 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71  utex_enter(), sq
37030 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37040 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  ), or.** sqlite3
37050 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69  _mutex_leave() i
37060 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37070 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65  , then all three
37080 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68   routines.** beh
37090 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  ave as no-ops..*
370a0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
370b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
370c0 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ld()] and [sqlit
370d0 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
370e0 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ()]..*/.sqlite3_
370f0 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d  mutex *sqlite3_m
37100 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b  utex_alloc(int);
37110 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
37120 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33  tex_free(sqlite3
37130 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
37140 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
37150 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  er(sqlite3_mutex
37160 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37170 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65  mutex_try(sqlite
37180 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20  3_mutex*);.void 
37190 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
371a0 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ave(sqlite3_mute
371b0 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
371c0 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68  3REF: Mutex Meth
371d0 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
371e0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
371f0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64  this structure d
37200 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c  efines the low-l
37210 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  evel routines.**
37220 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74   used to allocat
37230 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65  e and use mutexe
37240 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79  s..**.** Usually
37250 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  , the default mu
37260 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
37270 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
37280 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75  SQLite are.** su
37290 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65  fficient, howeve
372a0 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74  r the user has t
372b0 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62  he option of sub
372c0 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74  stituting a cust
372d0 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  om.** implementa
372e0 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c  tion for special
372f0 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73  ized deployments
37300 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20   or systems for 
37310 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20  which SQLite.** 
37320 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
37330 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
37340 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74  ementation. In t
37350 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73  his case, the us
37360 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e  er.** creates an
37370 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69  d populates an i
37380 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
37390 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73  structure to pas
373a0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
373b0 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77  config() along w
373c0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
373d0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
373e0 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  tion..** Additio
373f0 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e  nally, an instan
37400 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
37410 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
37420 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74   as an.** output
37430 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71   variable when q
37440 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74  uerying the syst
37450 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  em for the curre
37460 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  nt mutex.** impl
37470 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e  ementation, usin
37480 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
37490 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f  NFIG_GETMUTEX] o
374a0 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ption..**.** ^Th
374b0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
374c0 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
374d0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
374e0 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
374f0 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e  art of system in
37500 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20  itialization by 
37510 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  the sqlite3_init
37520 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  ialize() functio
37530 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  n..** ^The xMute
37540 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73  xInit routine is
37550 20 63 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65   calle by SQLite
37560 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f   exactly once fo
37570 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74  r each.** effect
37580 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ive call to [sql
37590 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
375a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
375b0 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
375c0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
375d0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
375e0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
375f0 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
37600 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
37610 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
37620 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
37630 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37640 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
37650 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
37660 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
37670 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
37680 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
37690 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
376a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
376b0 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
376c0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
376d0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
376e0 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65  hod.  ^The xMute
376f0 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66  xEnd().** interf
37700 61 63 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65  ace is invoked e
37710 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20  xactly once for 
37720 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  each call to [sq
37730 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
37740 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72  ]..**.** ^(The r
37750 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d  emaining seven m
37760 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62  ethods defined b
37770 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
37780 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a   (xMutexAlloc,.*
37790 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d  * xMutexFree, xM
377a0 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65  utexEnter, xMute
377b0 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76  xTry, xMutexLeav
377c0 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e  e, xMutexHeld an
377d0 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65  d.** xMutexNothe
377e0 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  ld) implement th
377f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
37800 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69  rfaces (respecti
37810 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  vely):.**.** <ul
37820 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37830 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37840 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  c()] </li>.**   
37850 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37860 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c  utex_free()] </l
37870 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37880 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
37890 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  er()] </li>.**  
378a0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
378b0 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c  mutex_try()] </l
378c0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
378d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
378e0 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ve()] </li>.**  
378f0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37900 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f  mutex_held()] </
37910 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
37920 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37930 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  theld()] </li>.*
37940 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
37950 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
37960 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20  nce is that the 
37970 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58  public sqlite3_X
37980 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75  XX functions enu
37990 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65  merated.** above
379a0 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
379b0 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73   any invocations
379c0 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c   that pass a NUL
379d0 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
379e0 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20  d.** of a valid 
379f0 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68  mutex handle. Th
37a00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37a10 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73  s of the methods
37a20 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74   defined.** by t
37a30 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72  his structure ar
37a40 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  e not required t
37a50 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61  o handle this ca
37a60 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a  se, the results.
37a70 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20  ** of passing a 
37a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
37a90 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20  tead of a valid 
37aa0 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65  mutex handle are
37ab0 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69   undefined.** (i
37ac0 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65 70 74  .e. it is accept
37ad0 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20  able to provide 
37ae0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37af0 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c 74 73  n that segfaults
37b00 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73   if.** it is pas
37b10 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  sed a NULL point
37b20 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  er)..**.** The x
37b30 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68  MutexInit() meth
37b40 6f 64 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  od must be threa
37b50 64 73 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74  dsafe.  ^It must
37b60 20 62 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a   be harmless to.
37b70 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78  ** invoke xMutex
37b80 49 6e 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74  Init() mutiple t
37b90 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  imes within the 
37ba0 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64  same process and
37bb0 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65   without.** inte
37bc0 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  rvening calls to
37bd0 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53   xMutexEnd().  S
37be0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
37bf0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
37c00 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75   xMutexInit() mu
37c10 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a  st be no-ops..**
37c20 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28  .** ^xMutexInit(
37c30 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53  ) must not use S
37c40 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  QLite memory all
37c50 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65  ocation ([sqlite
37c60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61  3_malloc()].** a
37c70 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65  nd its associate
37c80 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c  s).  ^Similarly,
37c90 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d   xMutexAlloc() m
37ca0 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
37cb0 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  te memory.** all
37cc0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74  ocation for a st
37cd0 61 74 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f  atic mutex.  ^Ho
37ce0 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f  wever xMutexAllo
37cf0 63 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69  c() may use SQLi
37d00 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  te.** memory all
37d10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61  ocation for a fa
37d20 73 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20  st or recursive 
37d30 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  mutex..**.** ^SQ
37d40 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
37d50 20 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29   the xMutexEnd()
37d60 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71   method when [sq
37d70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
37d80 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20  ] is.** called, 
37d90 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  but only if the 
37da0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d  prior call to xM
37db0 75 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65  utexInit returne
37dc0 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  d SQLITE_OK..** 
37dd0 49 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61  If xMutexInit fa
37de0 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20  ils in any way, 
37df0 69 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74  it is expected t
37e00 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72  o clean up after
37e10 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72   itself.** prior
37e20 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a   to returning..*
37e30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
37e40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37e50 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
37e60 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  utex_methods;.st
37e70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
37e80 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  ex_methods {.  i
37e90 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29  nt (*xMutexInit)
37ea0 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  (void);.  int (*
37eb0 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29  xMutexEnd)(void)
37ec0 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ;.  sqlite3_mute
37ed0 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63  x *(*xMutexAlloc
37ee0 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28  )(int);.  void (
37ef0 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c  *xMutexFree)(sql
37f00 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
37f10 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e   void (*xMutexEn
37f20 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ter)(sqlite3_mut
37f30 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
37f40 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65  MutexTry)(sqlite
37f50 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
37f60 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65  id (*xMutexLeave
37f70 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37f80 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37f90 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  exHeld)(sqlite3_
37fa0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20  mutex *);.  int 
37fb0 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  (*xMutexNotheld)
37fc0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37fd0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
37fe0 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72  I3REF: Mutex Ver
37ff0 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  ification Routin
38000 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  es.**.** The sql
38010 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
38020 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  ) and sqlite3_mu
38030 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f  tex_notheld() ro
38040 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e  utines.** are in
38050 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
38060 6e 73 69 64 65 20 61 73 73 65 72 74 28 29 20 73  nside assert() s
38070 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
38080 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20   SQLite core.** 
38090 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73 65  never uses these
380a0 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74   routines except
380b0 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72   inside an asser
380c0 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74  t() and applicat
380d0 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69  ions.** are advi
380e0 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68  sed to follow th
380f0 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f  e lead of the co
38100 72 65 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65  re.  ^The SQLite
38110 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72   core only.** pr
38120 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74  ovides implement
38130 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65  ations for these
38140 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69   routines when i
38150 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  t is compiled.**
38160 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
38170 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45  _DEBUG flag.  ^E
38180 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d  xternal mutex im
38190 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
381a0 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72   are only requir
381b0 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68  ed to provide th
381c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20  ese routines if 
381d0 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a  SQLITE_DEBUG is.
381e0 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69  ** defined and i
381f0 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20  f NDEBUG is not 
38200 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
38210 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73  These routines s
38220 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75  hould return tru
38230 65 20 69 66 20 74 68 65 20 6d 75 74 65 78 20 69  e if the mutex i
38240 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74  n their argument
38250 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e  .** is held or n
38260 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74  ot held, respect
38270 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61  ively, by the ca
38280 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a  lling thread..**
38290 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  .** ^The impleme
382a0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72  ntation is not r
382b0 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69  equired to provi
382c0 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ded versions of 
382d0 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  these.** routine
382e0 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20  s that actually 
382f0 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70  work. If the imp
38300 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
38310 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72   not provide wor
38320 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  king.** versions
38330 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
38340 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74  es, it should at
38350 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65 20 73   least provide s
38360 74 75 62 73 20 74 68 61 74 20 61 6c 77 61 79 73  tubs that always
38370 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20  .** return true 
38380 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73  so that one does
38390 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75   not get spuriou
383a0 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c  s assertion fail
383b0 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ures..**.** ^If 
383c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
383d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
383e0 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ld() is a NULL p
383f0 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74  ointer then.** t
38400 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  he routine shoul
38410 64 20 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68  d return 1.   Th
38420 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72  is seems counter
38430 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65  -intuitive since
38440 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20  .** clearly the 
38450 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20  mutex cannot be 
38460 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20  held if it does 
38470 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20  not exist.  But 
38480 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f  the.** the reaso
38490 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73  n the mutex does
384a0 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65   not exist is be
384b0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20  cause the build 
384c0 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20  is not.** using 
384d0 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65  mutexes.  And we
384e0 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65   do not want the
384f0 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69   assert() contai
38500 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  ning the.** call
38510 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
38520 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c  x_held() to fail
38530 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  , so a non-zero 
38540 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65  return is.** the
38550 20 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69   appropriate thi
38560 6e 67 20 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20  ng to do.  ^The 
38570 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
38580 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72  theld().** inter
38590 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f  face should also
385a0 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67   return 1 when g
385b0 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  iven a NULL poin
385c0 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ter..*/.#ifndef 
385d0 4e 44 45 42 55 47 0a 69 6e 74 20 73 71 6c 69 74  NDEBUG.int sqlit
385e0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71  e3_mutex_held(sq
385f0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69  lite3_mutex*);.i
38600 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
38610 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33  _notheld(sqlite3
38620 5f 6d 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66  _mutex*);.#endif
38630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38640 3a 20 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a  : Mutex Types.**
38650 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
38660 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20  _mutex_alloc()] 
38670 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65 73 20  interface takes 
38680 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
38690 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e  t.** which is on
386a0 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
386b0 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  er constants..**
386c0 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73  .** The set of s
386d0 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61  tatic mutexes ma
386e0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e  y change from on
386f0 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65  e SQLite release
38700 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
38710 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
38720 68 61 74 20 6f 76 65 72 72 69 64 65 20 74 68 65  hat override the
38730 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20   built-in mutex 
38740 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a  logic must be.**
38750 20 70 72 65 70 61 72 65 64 20 74 6f 20 61 63 63   prepared to acc
38760 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f  ommodate additio
38770 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
38780 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  es..*/.#define S
38790 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
387a0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
387b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
387c0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 20 20  TEX_RECURSIVE   
387d0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
387e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
387f0 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23  IC_MASTER    2.#
38800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
38810 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20  TEX_STATIC_MEM  
38820 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74       3  /* sqlit
38830 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23  e3_malloc() */.#
38840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
38850 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20  TEX_STATIC_MEM2 
38860 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55       4  /* NOT U
38870 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  SED */.#define S
38880 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38890 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20  IC_OPEN      4  
388a0 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f  /* sqlite3BtreeO
388b0 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  pen() */.#define
388c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
388d0 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35  ATIC_PRNG      5
388e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e    /* sqlite3_ran
388f0 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  dom() */.#define
38900 20 53 51 4c 49 54 45 5f 4d 55 54